# Node actions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/actions

Actions define the activities that a node handles. Actions have various types and specify communication details for plugins or integrations.

<Card title="Why is it important?" />

Node actions allow you to incorporate <Tooltip> **business rules** </Tooltip> into a <Tooltip> **process**</Tooltip>, and send data to front-end apps.

The FlowX.AI platform supports the following **types of node actions**:

<CardGroup>
  <Card title="Business rule" href="./business-rule-action/business-rule-action" icon="gavel" />

  <Card title="Save Data" icon="floppy-disk" />

  <Card title="Kafka send" href="../node/message-send-received-task-node" icon="share-from-square" />

  <Card title="Send data to user interface" href="./send-data-to-user-interface" icon="desktop" />

  <Card title="Upload file" href="./upload-file-action" icon="upload" />

  <Card title="Start subprocess" href="./start-subprocess-action" icon="play" />

  <Card title="Append params to parent process" href="./append-params-to-parent-process" icon="circle-plus" />

  <Card title="Start integration workflow" href="./start-integration-workflow" icon="plug" />

  <Card title="Start new project instance" href="./start-new-project-instance" icon="folder" />

  <Card title="Send notification" href="./send-notification-action" icon="paper-plane" />
</CardGroup>

<Info>
  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).
</Info>

Actions fall into two categories:

* Business rules
* User interactions

### Business rules

Actions use action rules such as MVEL expressions or scripts in JavaScript, Python, or Groovy to attach business rules to a node.

<Card title="Business rule action" href="./business-rule-action" icon="link" />

<Card title="Supported scripts" href="../supported-scripts" icon="link">
  For more information about supported scripting languages, see Supported scripts.
</Card>

<Hint>
  Each button on the user interface corresponds to a manual user action.
</Hint>

### Action edit

When configuring an action, the Action Edit panel provides three main configuration sections:

#### Trigger

This section defines how and when you can execute the action:

* **Manual**: Requires manual triggering through the REST API, typically by a user interaction in the interface (for example, clicking a button). When turned off, the action runs automatically.
* **Repeatable**: When enabled, you can trigger the action multiple times. When turned off, you can execute the action only once.

<Info>
  Manual actions can be either mandatory or optional. Automatic actions are always considered mandatory.
</Info>

#### Execution

This section controls the action's execution behavior:

* **Optional**: When enabled, the action is optional and the flow can advance without executing it. When turned off (default), the action is mandatory.
* **Autorun Children?**: When enabled, all child actions marked as mandatory and automatic run immediately after the parent action completes. Default is off.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/node_action.png)
</Frame>

<Info>
  If all mandatory actions on a node are not executed, the flow (token) doesn't advance.
</Info>

#### Navigation

This section controls user navigation behavior:

* **Allow back to this action**: Returns the token to this action from a downstream node only if you trigger the action manually.
  When enabled, you have the following "Back in steps" configuration options available:
  * **When returning to this action, reset process data**: Restores the process state and data to how it was before the initial execution of this action. Default is off.
  * **Copy the following objects from current state**: Specifies process keys that retain their data as persisted before you navigate back to this action.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_back_in_action.png)
</Frame>

### Action parameters

Action parameters store extra values as key/value pairs, such as topics for outgoing messages or message formats for the front-end.

## Configuring actions

Beyond the basic trigger, execution, and navigation settings described in the preceding section, actions have additional characteristics:

### Action order

When multiple actions exist on a single node, the system executes them in the order you define them.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/%20node_action1.png)
</Frame>

### Parent/child hierarchy

Actions can be organized in a parent/child hierarchy, allowing you to create dependent action chains. Child actions can be configured to:

* Run automatically after the parent completes (using **Autorun Children?**): When enabled, all child actions marked as mandatory and automatic run immediately after the parent action completes. Default is off.
* Execute as callbacks when responses are received from external systems

For more information on adding and managing actions, see the following section:

<Card title="Adding an action to a node" href="../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node" />

## Linking actions together

You can link actions together in two ways so that certain actions run immediately after others:

<Info>
  Certain actions can run immediately after another action by setting the `parentName` field on the action for callbacks. Callback actions are performed when the Engine receives a specific message, indicated by the `callbacksForAction` header in the message. To run actions immediately after the parent action, set the `autoRunChildren` flag to `true` for the parent action.
</Info>

### Child actions

A parent action has a flag `autoRunChildren`, set to `false` by default. When you set this flag to `true`, the child actions (the ones defined as mandatory and automatic) run immediately after the parent action completes execution.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/autorun_children.png)
</Frame>

### Callback actions

You can mark child actions as callbacks to run after receiving a reply from an external system. Set these actions when defining the interaction with the external system (the [Kafka send action](../node/message-send-received-task-node#configuring-a-message-send-task-node)).

For example, you can use a callback function to handle a user's interaction with a web page, such as uploading a file. When the user performs the action, the callback function executes, allowing the web app to respond appropriately.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/callback2.png)
</Frame>

#### Example

Add callback actions in the **Advanced configuration** tab, in the **header** parameter `callbacksForAction`.

```js theme={"system"}
{"processInstanceId": ${processInstanceId}, "destinationId": "upload_file", "callbacksForAction": "upload_file"}
```

* `callbacksForAction`: The value of this key is a string that specifies a callback action associated with the `upload_file` destination ID. This is part of an event-driven system (Kafka send action) where the system calls this callback after the `upload_file` action completes.


# Append params to parent process
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/append-params-to-parent-process

It is a type of action that allows you to send data from a subprocess to a parent process.

**Why is it important?**  If you are using subprocesses that produce data that needs to be sent back to the main **process**, you can do that by using an **Append Params to Parent Process** action.

<Info>
  This action writes data into the **parent process data model** permanently. To push real-time updates to the parent UI without modifying the data model, use [Send data to user interface](./send-data-to-user-interface) with Target Process set to Parent. For a comparison of all data passing mechanisms, see [Subprocess management - How data flows](../process/subprocess#how-data-flows-between-subprocess-and-parent).
</Info>

## When to use this action

In a synchronous subprocess (Start Async = OFF on the Start Subprocess action), prefer **Data Mapping** on the Start Subprocess action — it propagates results back to the parent automatically when the subprocess ends, without an extra action.

Append Params to Parent Process is the right choice when:

* **The subprocess runs asynchronously** (Start Async = ON on the Start Subprocess action). The parent doesn't wait for the subprocess to finish, so Data Mapping doesn't apply — the subprocess must push results to the parent itself.
* **The subprocess is long-running** (LLM agents, slow integrations, batch jobs) and you want fire-and-forget execution while the user continues in the UI.

<Frame>
  ![Main process with two async subprocesses started in parallel before a converging gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/append_param_1.png)
</Frame>

### Combined with Send data to user interface

To both persist the result AND notify the user's UI in a single step, attach two actions to the final node of the async subprocess:

1. **Append Params to Parent Process** — writes the result into the parent's data model.
2. **Send data to user interface** with Target Process set to Parent — pushes a UI update over SSE.

This is the standard pattern for async agent results: data is persisted so downstream nodes can read it, and the user sees the update appear without refreshing.

<Frame>
  ![Two actions configured on the final node of an async subprocess — Append Params to Parent Process and Send data to user interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/append_param_2.png)
</Frame>

## Configuring an Append params to parent process

After you create a process designed to be used as a [subprocess](../process/subprocess), you can configure the action. To do this, you need to add an **Append Params to Parent Process** on a [**Task node**](../node/task-node) in the subprocess.

The following properties must be configured:

* [Action Edit](#action-edit)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)

### Action edit

* **Name** — internal identifier for the action. We recommend defining a naming standard so actions are easy to find.
* **Action Type** — set to **Append Params to Parent Process**.

The remaining options are grouped into three columns:

**Trigger**

* **Manual** — when ON, the action runs only after a user triggers it (for example, from a button in a UI Task). When OFF, the action runs automatically as soon as the token reaches the node. For Append Params, leave this OFF in most cases.
* **Repeatable** — when ON, the action can be triggered multiple times.

**Execution**

* **Optional** — automatic actions cannot be optional. Manual actions can be optional or required.
* **Autorun Children?** — when ON, child actions (mandatory and automatic) run immediately after this action finishes.

**Navigation**

* **Allow back to this action** — when ON, the user can return to this action via the back-in-process functionality. The toggle is enabled only when **Manual** is ON. For details, see [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process).

### Parameters

All three fields below are mandatory.

* **Copy from current state** - data that you want to be copied back to the parent process
* **Destination in the parent state** - on what key to copy the param values
* **Show Target Process** - ID of the parent process where the params are written. Set this to `${parentProcessInstanceId}` if the variable was defined when you [started the subprocess](./start-subprocess-action). If this value is missing or cannot be parsed as a process instance ID, the action raises a `MISSCONFIG_SUBPROCESS` incident on the parent process — it does not fail silently.

<Check>
  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.
</Check>

<Warning>
  **The payload always lands at the destination key — don't repeat the key in both fields.** If **Copy from current state** is `{"clickCount": ${clickCount}}` and **Destination in the parent state** is `clickCount`, the parent receives a nested object at `clickCount.clickCount`, not the value at `clickCount`. To write a single value to a top-level parent key, use a raw value reference instead: set **Copy from current state** to `${clickCount}` and **Destination in the parent state** to `clickCount`. Raw references work for numbers, booleans, objects, and arrays; wrap string values in quotes (`"${myKey}"`).

  **The action replaces the value at the destination key.** If the destination key already contains a nested object — for example `application.client = {"name": "Alice", "age": 30}` — sending `{"age": 35}` to destination `application.client` overwrites the entire object and `name` is lost. To preserve siblings, write to a destination key that doesn't conflict with existing parent state (for example, `application.subprocessResult.client` instead of `application.client`), or use [Send data to user interface](./send-data-to-user-interface) with Target Process set to Parent for non-destructive updates.
</Warning>

### 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)

<Warning>
  **Data to send** is configurable only when the **Manual** toggle is ON.
</Warning>

## Example

We have a subprocess that allows us to enter the age of the client on the **data.client.age** key, and we want to copy the value back to the parent process. The key to which we want to receive this value in the parent process is **application.client.age**.

This is the configuration to apply the above scenario:

**Parameters**

* **Copy from current state** - `{"age": ${data.client.age}}` — the JSON payload to send to the parent
* **Destination in the parent state** - `application.client` — the key on the parent where the payload is written. Combined with the payload above, the value lands at `application.client.age`.
* **Show Target Process** - `${parentProcessInstanceId}` — required, identifies the parent process


# Business rules types
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action

A business rule is an action type in FlowX.AI that allows you to configure a script on a BPMN node. It's a way to specify business logic or decision-making processes in a business process.

The script can read and write the data available on the process at the moment the script is executed. For this reason, it is very important to understand what data is available on the process when the script is executed.

Business rules can be attached to a node by using actions with [**action rules**](../actions#business-rules) on them. These can be specified using MVEL expressions, or scripts written in JavaScript, Python, or Groovy.

![Business rule action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/business_rule_action.png)

For more information about supported scripting languages, see the next section:

<Card title="Supported scripts" href="../../supported-scripts" icon="link" />

You can also test your rules by using the **Test Rule** function.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/test_rule_function.png)

## Configuration

To use a Business Rules Action, follow these steps:

1. **Select a BPMN Task Node**: Choose the BPMN task node to which you want to attach the Business Rules Action. This could be a Service Task, User Task, or another task type that supports actions.
2. **Define the Action**: In the task node properties, configure the "Business Rules Action" field and select the desired language (MVEL, Java, JavaScript or Python).
3. **Write the Business Rule**: In the selected language, write the business rule or decision logic. This rule should take input data, process it, and possibly generate an output or result.
4. **Input and Output Variables**: Ensure that the task node can access the necessary input variables from the BPMN process context and store any output or result variables as needed.
5. **Execution**: When the BPMN process reaches the task node, the attached Business Rules Action is executed, and the defined business rule is evaluated.
6. **Result**: The result of the business rule execution may affect the flow of the BPMN process, update process variables, or trigger other actions based on the logic defined in the rule.

Let's take look at the following example. We have some data about the gender of a user and we need to create a business rule that computes the formal title based on the gender:

1. This is how the process instance data looks like before it reaches the business rule:

   ```json theme={"system"}
   {
       "application" : {
           "client" : 
           {
               "firstName" : "David",
               "surName" : "James",
               "gender" : "M",
               
           }
       }
   }
   ```
2. When the token reaches this node the following script (defined for the business rule) is executed. The language used here for scripting is MVEL.

```java theme={"system"}
if (input.application.client.gender == 'F') {
    output.put("application", {
        "client": {
            "salutation": "Ms"
        }
    });
} else if (input.application.client.gender == 'M') {
    output.put("application", {
        "client": {
            "salutation": "Mr"
        }
    });
} else {
    output.put("application", {
        "client": {
            "salutation": "Mx"
        }
    });
}
```

3. After the script is executed, the process instance data will look like this:

```json theme={"system"}
{
    "application": {
        "client": {
            "firstName": "David",
            "surName": "James",
            "gender": "M",
            "salutation": "Mr"
        }
    }
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/mvel_example.gif)

## Flattened vs unflattened keys

<Warning>
  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.
</Warning>

![Obsolete business rule](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/obsolete_business_rule.png)

## Business rules examples

<Tip>
  Examples available for [**v2.5.0**](https://old-docs.flowx.ai/release-notes/v2.5.0-april-2022/) version and higher
</Tip>

We will use the MVEL example used above to rewrite it in other scripting languages formats:

<Tabs>
  <Tab title="MVEL">
    ```Java theme={"system"}
    if (input.application.client.gender == 'F') {
            output.put("application", {
                "client": {
                    "salutation": "Ms"
                }
             });
        } else if (input.application.client.gender == 'M') {
            output.put("application", {
                "client": {
                    "salutation": "Mr"
                }
             });
        } else {
            output.put("application", {
                "client": {
                    "salutation": "Mx"
                }
            });
        }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
        if input.get("application").get("client").get("gender") == "F":
            output.put("application", {
                "client" : {
                    "salutation" : "Ms"
                }
            })
        elif input.get("application").get("client").get("gender") == "M":
            output.put("application", {
                "client" : {
                    "salutation" : "Mr"
                }
            })
        else:
            output.put("application", {
                    "client" : {
                        "salutation" : "Mx"
                    }
                })
    ```
  </Tab>

  <Tab title="JS">
    ```js theme={"system"}
    if (input.application.client.gender === 'F') {
        output.application = {
            client: {
                salutation: 'Ms'
            }
        };
    } else if (input.application.client.gender === 'M') {
        output.application = {
            client: {
                salutation: 'Mr'
            }
        };
    } else {
        output.application = {
            client: {
                salutation: 'Mx'
            }
        };
    }
    ```
  </Tab>

  <Tab title="Groovy">
    ```groovy theme={"system"}
    if (input.application.client.gender === 'F') {
    def gender = input.application.client.gender
    switch (gender) {
        case 'F':
            output.application = [client: [salutation: 'Ms']]
            break
        case 'M':
            output.application = [client: [salutation: 'Mr']]
            break
        default:
            output.application = [client: [salutation: 'Mx']]
    }
    ```
  </Tab>
</Tabs>


# Extracting additional data in business rules
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/business-rule-action/extracting-additional-data

Business rules in FlowX.AI allow you to extract and use key values dynamically. This is essential for handling user security details, configuration parameters, and business logic calculations.

<Info>
  This guide is covering the following:

  ✅ Retrieving security details dynamically\
  ✅ Extracting specific user attributes\
  ✅ Fetching configuration parameters
</Info>

## Extracting security details

Security details (`securityDetails`) store user-related data, including **email, username, roles, and permissions**. These values are stored in `additionalData.securityDetails` and can be accessed dynamically within business rules and workflow scripts.

<Info>
  The `securityDetails` structure differs between **processes** and **workflows**. Processes group security details by swimlane and role, while workflows use a simplified flat structure. See the tabs below for both formats.
</Info>

<Tabs>
  <Tab title="In processes">
    ### Retrieve security details

    Use the following business rule to fetch and store security details:

    ```JavaScript theme={"system"}
    // Retrieve security details from additionalData
    securityDetails = additionalData.get("securityDetails");

    // Store the extracted security details
    output.put("securityDetails", securityDetails);
    ```

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2813%29.png)
    </Frame>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-25%20at%2013.32.37.png)
    </Frame>

    Example output:

    ```json theme={"system"}
    {
        "securityDetails": {
            "Default": {
                "owner": {
                    "username": "user@email.com",
                    "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600",
                    "details": {
                        "firstName": "John",
                        "lastName": "Snow",
                        "email": "user@email.com",
                        "jwt": "your_jwt",
                        "roles": [],
                        "groups": [
                            "/Users/Flowx_demo",
                            "/superAdmin"
                        ],
                        "attributes": {}
                    }
                }
            }
        }
    }
    ```

    In processes, `securityDetails` is grouped by **swimlane name** (e.g., `Default`) and **role** (e.g., `owner`). This structure reflects the BPMN swimlane and role assignments configured in the process definition.

    ### Extract specific owner details

    To retrieve specific attributes, such as email, username, first name, and last name, use one of the following scripts (JS or Python):

    <Tabs>
      <Tab title="JavaScript">
        ```javascript theme={"system"}
        // Retrieve security details
        securityDetails = additionalData.get("securityDetails");
        // Extract owner details from the Default swimlane
        email = securityDetails.Default.owner.details.email;
        username = securityDetails.Default.owner.username;
        firstName = securityDetails.Default.owner.details.firstName;
        lastName = securityDetails.Default.owner.details.lastName;

        // Store extracted details in the output
        output.put("email", email);
        output.put("username", username);
        output.put("firstName", firstName);
        output.put("lastName", lastName);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        # Retrieve security details
        security_details = additionalData.get("securityDetails")
        # Extract owner details from the Default swimlane
        email = security_details["Default"]["owner"]["details"]["email"]
        username = security_details["Default"]["owner"]["username"]
        first_name = security_details["Default"]["owner"]["details"]["firstName"]
        last_name = security_details["Default"]["owner"]["details"]["lastName"]

        # Store extracted details in the output
        output["email"] = email
        output["username"] = username
        output["firstName"] = first_name
        output["lastName"] = last_name
        ```
      </Tab>
    </Tabs>

    Extracted values:

    * **Owner Email** (`securityDetails.Default.owner.details.email`)
    * **Username** (`securityDetails.Default.owner.username`)
    * **First Name** (`securityDetails.Default.owner.details.firstName`)
    * **Last Name** (`securityDetails.Default.owner.details.lastName`)

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2814%29.png)
    </Frame>

    ### Dynamic extraction by swimlane

    If your application uses multiple swimlanes, retrieve the owner details dynamically:

    ```JavaScript theme={"system"}
    // Get security details
    securityDetails = additionalData.get("securityDetails");

    // Extract owner details based on the swimlane
    ownerDetails = securityDetails.Default.owner.details;

    <Info>
    Default is the swimlane name in this example. Replace it with your swimlane name.
    </Info>

    // Store extracted values in the process instance
    output.put("email", ownerDetails.email);
    output.put("username", securityDetails.Default.owner.username);
    output.put("firstName", ownerDetails.firstName);
    output.put("lastName", ownerDetails.lastName);
    ```

    Example output:

    ```json theme={"system"}
    {
      "email": "user@email.com",
      "username": "user@email.com",
      "firstName": "John",
      "lastName": "Snow"
    }
    ```
  </Tab>

  <Tab title="In workflows">
    ### Retrieve security details

    In workflow scripts, `securityDetails` uses a **flat structure** — there is no swimlane or role grouping, since workflows do not have swimlanes.

    ```javascript theme={"system"}
    // Retrieve all additional data
    const additionalParams = additionalData;

    // Access security details directly
    output.put("securityDetails", additionalParams.securityDetails);
    ```

    Example output:

    ```json theme={"system"}
    {
      "securityDetails": {
        "username": "user@email.com",
        "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600",
        "details": {
          "firstName": "John",
          "lastName": "Snow",
          "email": "user@email.com",
          "roles": ["ROLE_ADMIN", "ROLE_USER"],
          "groups": ["/Users/Flowx_demo", "/superAdmin"],
          "attributes": {}
        }
      }
    }
    ```

    | Field                | Description                                                                             |
    | -------------------- | --------------------------------------------------------------------------------------- |
    | `username`           | The authenticated user's username                                                       |
    | `identifier`         | The user's unique identifier (Keycloak subject ID)                                      |
    | `details.firstName`  | User's first name                                                                       |
    | `details.lastName`   | User's last name                                                                        |
    | `details.email`      | User's email address                                                                    |
    | `details.roles`      | Roles assigned to the user in the authentication token                                  |
    | `details.groups`     | Groups the user belongs to in the authentication token                                  |
    | `details.attributes` | Additional user attributes from the authentication token (empty object if none are set) |

    <Note>
      Unlike process `securityDetails`, workflows do not include the `jwt` field, and they use a flat structure (no swimlane or role grouping).
    </Note>

    ### Extract specific user details

    Since the structure is flat, you can access user attributes directly without navigating swimlane or role levels:

    <Tabs>
      <Tab title="JavaScript">
        ```javascript theme={"system"}
        // Retrieve security details
        securityDetails = additionalData.securityDetails;

        // Extract user details directly (no swimlane grouping)
        email = securityDetails.details.email;
        username = securityDetails.username;
        identifier = securityDetails.identifier;
        firstName = securityDetails.details.firstName;
        lastName = securityDetails.details.lastName;
        roles = securityDetails.details.roles;
        groups = securityDetails.details.groups;

        // Store extracted details in the output
        output.put("email", email);
        output.put("username", username);
        output.put("identifier", identifier);
        output.put("firstName", firstName);
        output.put("lastName", lastName);
        output.put("roles", roles);
        output.put("groups", groups);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        # Retrieve security details
        security_details = additionalData["securityDetails"]

        # Extract user details directly (no swimlane grouping)
        email = security_details["details"]["email"]
        username = security_details["username"]
        identifier = security_details["identifier"]
        first_name = security_details["details"]["firstName"]
        last_name = security_details["details"]["lastName"]
        roles = security_details["details"]["roles"]
        groups = security_details["details"]["groups"]

        # Store extracted details in the output
        output["email"] = email
        output["username"] = username
        output["identifier"] = identifier
        output["firstName"] = first_name
        output["lastName"] = last_name
        output["roles"] = roles
        output["groups"] = groups
        ```
      </Tab>
    </Tabs>

    Extracted values:

    * **Email** (`securityDetails.details.email`)
    * **Username** (`securityDetails.username`)
    * **Identifier** (`securityDetails.identifier`)
    * **First Name** (`securityDetails.details.firstName`)
    * **Last Name** (`securityDetails.details.lastName`)
    * **Roles** (`securityDetails.details.roles`)
    * **Groups** (`securityDetails.details.groups`)

    ### Structure comparison

    | Field      | Process path                                       | Workflow path                        |
    | ---------- | -------------------------------------------------- | ------------------------------------ |
    | Email      | `securityDetails.Default.owner.details.email`      | `securityDetails.details.email`      |
    | Username   | `securityDetails.Default.owner.username`           | `securityDetails.username`           |
    | Identifier | `securityDetails.Default.owner.identifier`         | `securityDetails.identifier`         |
    | First Name | `securityDetails.Default.owner.details.firstName`  | `securityDetails.details.firstName`  |
    | Last Name  | `securityDetails.Default.owner.details.lastName`   | `securityDetails.details.lastName`   |
    | Roles      | `securityDetails.Default.owner.details.roles`      | `securityDetails.details.roles`      |
    | Groups     | `securityDetails.Default.owner.details.groups`     | `securityDetails.details.groups`     |
    | Attributes | `securityDetails.Default.owner.details.attributes` | `securityDetails.details.attributes` |
    | JWT        | `securityDetails.Default.owner.details.jwt`        | Not available                        |

    <Warning>
      If you are migrating business rule logic from a process to a workflow, update the `securityDetails` access paths. The swimlane (e.g., `Default`) and role (e.g., `owner`) levels do not exist in the workflow structure.
    </Warning>
  </Tab>
</Tabs>

***

## Extracting values from configuration parameters

To make business rules flexible, store configuration values in project configuration parameters instead of hardcoding them.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2816%29.png)
</Frame>

### Retrieve configuration parameters

Use a business rule to fetch and store configuration parameter values dynamically:

```JavaScript theme={"system"}
// Retrieve a configuration parameter (e.g., commission percentage)
commissionPercentage = additionalData.applicationConfiguration.get("commissionPercentage");

// Store the retrieved value in output in the process instance
output.put("commissionPercentage", commissionPercentage);

```

### Example use case: commission calculation

This example shows how to calculate a commission value dynamically using a configuration parameter.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.54.47.png)
</Frame>

#### Configuration parameters

| **Parameter Name**     | **Description**                                 | **Example Value** |
| ---------------------- | ----------------------------------------------- | ----------------- |
| `commissionPercentage` | The percentage used to calculate the commission | `0.05` (5%)       |

<Tip>
  Configuration parameters can be modified in:

  ➡ FlowX.AI Designer → Your Project → Configuration Parameters
</Tip>

#### Process flow

<Steps>
  <Step title="User Inputs an Amount">
    In a User task we have an input UI element where the user provides an amount (`userInputAmount`).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.56.41.png)
    </Frame>
  </Step>

  <Step title="Retrieve Commission Percentage from Configuration">
    In the next node, a Service Task fetches the `commissionPercentage` from the configuration parameters.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.59.57.png)
    </Frame>

    Business rule used:

    ```JavaScript theme={"system"}
    // Retrieve user input
    amount = input.get("userInputAmount");

    // Retrieve a value from configuration
    commissionPercentage = additionalData.applicationConfiguration.get("commissionPercentage");

    // Apply the configuration value
    commissionValue = amount * commissionPercentage;

    // Store the calculated result in the process instance
    output.put("commissionValue", commissionValue);

    ```
  </Step>

  <Step title="Calculate Commission">
    Formula used to calculate the commission:

    $$
    \text{commissionValue} = \text{userInputAmount} \times \text{commissionPercentage}
    $$
  </Step>

  <Step title="Store and Output the Result">
    The computed `commissionValue` is stored for further processing.

    Final result:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-27%2014.21.53.gif)
    </Frame>
  </Step>
</Steps>

<Tip>
  Why Use Configuration Parameters?

  ✅ Keep business rules flexible by avoiding hardcoded values.\
  ✅ Adapt calculations dynamically based on environment settings.\
  ✅ Simplify updates by modifying values in the project configuration rather than editing business rules.
</Tip>


# Kafka send action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/kafka-send-action

The FlowX.AI Designer offers various options to configure the Kafka Send Action through the Actions tab at the node level.

* [Action Edit](#action-edit)
* [Parameters](#parameters)

<Frame>
  ![Kafka Send Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/kafka_send_action_confg.gif)
</Frame>

### 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.

<Info>
  The Kafka Send Action type is always **Automatic**. Typically, Kafka Send Actions automatically trigger when the process reaches this step.
</Info>

* **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.

<Info>
  For detailed information on **Integrations management**, refer to [<u>**this link**</u>](../../platform-deep-dive/integrations/integration-designer).
</Info>

* **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.

<Frame>
  ![Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/message_send_parameters.png)
</Frame>

## Dynamic Kafka topics

You can use dynamic topic names for Kafka Send and Kafka Receive actions in FlowX.AI processes by leveraging Configuration Parameters. This enables flexibility when working with Kafka topics across different environments or use cases.

Steps to Create Dynamic Kafka Topics:

<Steps>
  <Step title="Define Configuration Parameters for Kafka Topics">
    Navigate to **Projects → Your Project → Configuration Parameters** in FlowX.AI Designer.

    Add or update configuration keys for Kafka topics.

    Example:

    * Key: `kafka_send_2`
    * Value: `ai.flowx.plugin.document.trigger`
    * Key: `kafka_receive`
    * Value: `ai.flowx.engine.receive.plugin.document`

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2017.47.57.png)
    </Frame>

    This allows referencing these parameters dynamically in your Kafka actions.
  </Step>

  <Step title="Use Configuration Parameters in Kafka Send Action">
    Open the process where you want to configure the Kafka Send Action.

    Go to Node Config > Actions.

    Select Kafka Send Action as the action type.

    Under Parameters, locate the Topics field.

    Use a dynamic reference to concatenate a parameter with another value:

    `${kafka_send_2}.${topic2}`

    Here:

    * `${kafka_send_2}` dynamically pulls the value from Configuration Parameters.
    * `${topic2}` can be another dynamic input set within the process.
  </Step>

  <Step title="Configure the Kafka Message Payload">
    Define the JSON structure for the message payload.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2018.03.36.png)
    </Frame>

    Ensure that all required fields align with the expected schema of the consuming system.
  </Step>

  <Step title="Validate and Test the Configuration">
    Start the process and check whether messages are correctly sent to the Kafka topic.

    If needed, modify the configuration parameters to change the topic dynamically.
  </Step>
</Steps>

## Kafka send action scenarios

The Kafka Send action serves as a versatile tool that facilitates communication across various systems and plugins, enabling efficient data transfer, reliable document management, notifications, and process initiation.

This action finds application in numerous scenarios while configuring processes:

* **Communicating with External Services**
* **Interacting with Connectors** - For example, integrating a connector in the FlowX.AI Designer [here](../../platform-deep-dive/integrations/building-a-connector#integrating-a-connector-in-flowxai-designer).
* **Engaging with Plugins:**
  * **Document Plugin:**
    * Generating, uploading, converting, and splitting documents - Explore examples [here](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview).
    * Updating/deleting documents - Find an example [here](../../platform-deep-dive/core-extensions/content-management/documents-plugin/deleting-a-file)
    * Optical Character Recognition (OCR) integration - View an example [here](../../platform-deep-dive/plugins/custom-plugins/ocr-plugin#scenario-for-flowxai-generated-documents).
  * **Notification Plugin:**
    * Sending notifications - Example available [here](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification) and emails with attachments [here](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments).
    * One-Time Password (OTP) generation and validation - Refer to these examples for [generating](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/generate-otp) and [validating](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/validate-otp) an OTP.
    * Forwarding notifications to external systems - Explore this [example](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/forwarding-notifications-to-an-external-system).
  * **OCR Plugin**
  * **Customer Management Plugin**
  * **Task Management Plugin:**
    * Bulk operations update - Find an example [here](../../platform-deep-dive/core-extensions/task-management/task-management-overview#bulk-updates).
* **Requesting Process Data for Forwarding or Processing** - For example, Data Search [here](../../platform-deep-dive/core-extensions/search-data-service).
* **Initiating Processes** - Starting a process via Kafka. Find examples [here](../../flowx-designer/managing-a-project-flow/starting-a-process).

The Kafka Send action stands as a versatile facilitator, enabling smooth operations in communication, document management, notifications, and process initiation across diverse systems and plugins.


# Send data to user interface
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/send-data-to-user-interface

Push real-time updates from the process to the client over a single long-lived HTTP connection using Server-Sent Events (SSE).

**Why is it useful?** It provides real-time updates and communication between the **process** and the frontend application.

<Info>
  This action pushes data to the **UI only** via SSE. It does not modify the parent process data model. To persist data from a subprocess into the parent process, use [Append Params to Parent Process](./append-params-to-parent-process). For a comparison of all data passing mechanisms, see [Subprocess management - How data flows](../process/subprocess#how-data-flows-between-subprocess-and-parent).
</Info>

## Configuring a Send data to user interface action

Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure a Send data to user interface, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-a-new-node), which has the following configuration options:

* [Action Edit](#action-edit)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)

### Action Edit

* **Name** — internal identifier for the action. We recommend defining a naming standard so actions are easy to find.
* **Action Type** — set to **Send data to user interface**.

The remaining options are grouped into three columns:

**Trigger**

* **Manual** — when ON, the action runs only after a user triggers it (for example, from a button in a UI Task). When OFF, the action runs automatically as soon as the token reaches the node.
* **Repeatable** — when ON, the action can be triggered multiple times.

**Execution**

* **Optional** — automatic actions cannot be optional. Manual actions can be optional or required.
* **Autorun Children?** — when ON, child actions (mandatory and automatic) run immediately after this action finishes.

**Navigation**

* **Allow back to this action** — when ON, the user can return to this action via the back-in-process functionality. The toggle is enabled only when **Manual** is ON. For details, see [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process).

<Frame>
  ![Send data to user interface action edit panel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/send_data_UI_1.png)
</Frame>

### Parameters

The following fields are required for a minimum configuration of this type of action:

* **Message Type** — one of four options. Each maps to a distinct SSE `messageType` on the wire:
  * **Default** (sent as `data`) — push a JSON payload to the UI. Most common case.
  * **Action** (sent as `runAction`) — tell the UI to perform an action. The Message must define a `type` field set to one of the supported [action types](../ui-designer/event-handlers#action-types) (`DISMISS`, `ACTION`, `START_PROCESS_INHERIT`, `UPLOAD`, `EXTERNAL`).
  * **General** (sent as `generalData`) — push the process's general data (configured under **Process Settings → General**) to the UI.
  * **Process Metadata** (sent as `processMetadata`) — push process instance metadata to the UI.

<Warning>
  To start a new process from a Send data to user interface action, set **Message Type** to **Action** and define a **Message** with the following format:
</Warning>

```json theme={"system"}
{
  "processName": "demoProcess",
  "type": "START_PROCESS_INHERIT",
  "clientDataKeys":["webAppKeys"],
  "params": {
     "startCondition": "${startCondition}",
     "paramsToCopy": []
     }
}
```

<Info>
  * `paramsToCopy` — choose which keys from the parent process parameters are copied to the subprocess
  * `withoutParams` — choose which keys from the parent process parameters are excluded when copying
</Info>

* **Message** — the JSON payload to send. You can use constant values and substitutions from process instance data.
* **Replace Values** — toggle next to the Message field, ON by default. When ON, `${...}` placeholders in the message are replaced with the corresponding values from process instance data before the message is sent. When OFF, the message is sent as literal text, with `${...}` placeholders left unresolved. The same toggle appears on other action parameters (for example, on Start Subprocess) and behaves the same way: it controls placeholder substitution for that parameter, before the action executes.
* **Target Process** — the running process instance the message is sent to. Options: **Active process** (`${processInstanceUuid}`) or **Parent process** (`${parentProcessInstanceUuid}`).

<Info>
  When this action runs inside a subprocess (started via [Start Subprocess](./start-subprocess-action), a [Call activity node](../node/call-subprocess-tasks/call-activity-node), or an embedded subprocess), set **Target Process** to **Parent process** to push the message to the user's UI session bound to the parent process.
</Info>

### 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)

<Warning>
  **Data to send** is configurable only when the **Manual** toggle is ON.
</Warning>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/websocket_data_to_send.gif)
</Frame>

### 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**.

<Frame>
  ![Send data to user interface — Message and Target Process configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/send_data_UI_2.png)
</Frame>


# Send notification action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/send-notification-action

Send emails directly from process nodes using the Send Notification action. Supports both new outbound emails and replies to received emails.

## Overview

The Send Notification action enables process nodes to send emails directly through a predefined email connection. It supports two modes:

* **New email mode** - Send a new email to specified recipients
* **Reply mode** - Reply to an email that triggered the process (using data from an [Email Trigger](../../platform-deep-dive/integrations/email-trigger) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) data source)

This differs from the existing [Kafka send](../node/message-send-received-task-node) notification approach: instead of publishing a message to Kafka for the Notifications Plugin to process, the Send Notification action sends the email directly through an email connection configured as an [Email Sender](../../platform-deep-dive/integrations/email-sender) (SMTP) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) (MS Graph) data source.

<Info>
  Notification templates configured before this feature for Kafka-based sending continue to work without modification.
</Info>

<Tip>
  **Recommended for new processes.** The Send Notification action provides typed, validated configuration fields and is the simpler choice for outbound emails. The [Kafka-based sending guide](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments) remains fully supported for existing processes and advanced cases where you need to craft the notification payload yourself.
</Tip>

***

## Prerequisites

Before using the Send Notification action, ensure you have:

1. An [Email Sender](../../platform-deep-dive/integrations/email-sender) (SMTP) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) (MS Graph) data source configured in Integration Designer (or a Default Server configured at the environment level)
2. A [notification template](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates) with **Email Server** set to **Predefined Email Connection**

***

## Adding the action

The Send Notification action is available on the following node types:

* [Send Message Task](../node/message-send-received-task-node#message-send-task)
* [Task](../node/task-node)
* [User Task](../node/user-task-node)

To add the action:

1. Select a node in your process definition
2. Open the **Actions** tab
3. Click **Add action**
4. Set **Action type** to **Send Notification**

<Frame>
  ![Send Notification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/et1.png)
</Frame>

***

## Configuration

### Notification template

<ParamField type="select">
  Select the notification template to use for the email content.

  <Info>
    Only notification templates with **Email Server** set to **Predefined Email Connection** appear in this list.
  </Info>
</ParamField>

### Data mapping

The **Data Mapping** section contains the email delivery settings, starting with the reply toggle.

<ParamField type="boolean">
  Toggle this setting to reply to the email that started the process.

  **Default:** OFF

  <Info>
    When enabled, the reply is sent only to the original sender unless you configure CC or BCC Receivers. The subject is automatically set to `RE: <original email subject>`.
  </Info>
</ParamField>

***

## Reply mode (reply toggle ON)

When **Reply to received emails** is enabled, the action replies to the email that triggered the current process instance. The email is sent to the original sender, and the subject is automatically prefixed with `RE:`.

<ParamField type="object">
  The process variable key that contains the `headerParams` object from the original email received through an [Email Trigger](../../platform-deep-dive/integrations/email-trigger).

  **Example:** `${replyField}`

  <Info>
    The `headerParams` object includes the `Message-ID` and other headers from the original email, which are required to maintain the email conversation thread.
  </Info>
</ParamField>

<ParamField type="string">
  The process variable key that resolves to a language code for the notification template.

  **Examples:** `en`, `ro`, `fr`

  <Tip>
    Use a process variable key that resolves to a language code — for example, `"en"` or `"ro"`.
  </Tip>
</ParamField>

<ParamField type="json">
  Optional file attachments. Enter a JSON object (single attachment) or array of JSON objects (multiple), or a process variable that resolves to the same shape.

  Each attachment requires:

  * `path` — file storage key (for example, `flowx-document-plugin-.../file.pdf`), not a local OS path
  * `filename` — name shown to the recipient

  **Example:**

  ```json theme={"system"}
  [{"path": "flowx-document-plugin-.../report.pdf", "filename": "Report.pdf"}]
  ```

  <Frame>
    ![Attachments field example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/attachments.png)
  </Frame>

  <Warning>
    On SMTP, omitting `filename` results in an unnamed attachment. Always set it.
  </Warning>
</ParamField>

<ParamField type="string | array">
  The recipients for the reply. If left empty, the reply is automatically sent to the original sender (`emailMessage.sender`). Use a process variable or explicit list to override.

  **Example:** `${emailMessage.sender}`

  <Tip>
    For multiple addresses, enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.
  </Tip>
</ParamField>

<ParamField type="string | array">
  CC recipients for the reply email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

  <Warning>
    Original CC recipients are **not** preserved automatically. If this field is empty, the reply is sent without any CC. To reply-all, pass `${emailMessage.cc}` explicitly (or build your own list).
  </Warning>
</ParamField>

<ParamField type="string | array">
  BCC recipients for the reply email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

  <Info>
    BCC recipients from the original email are not visible on incoming messages and cannot be inherited. Set this field explicitly if you need BCCs on the reply.
  </Info>
</ParamField>

<ParamField type="object">
  Map data sent from the process through the template. Use the JSON editor to define key-value pairs matching the data model in your notification template.
</ParamField>

***

## New email mode (reply toggle OFF)

When **Reply to received emails** is turned off, the action sends a new email to the specified recipients.

<ParamField type="string">
  The process variable key that resolves to a language code for the notification template.

  **Examples:** `en`, `ro`, `fr`

  <Tip>
    Use a process variable key that resolves to a language code — for example, `"en"` or `"ro"`.
  </Tip>
</ParamField>

<ParamField type="json">
  Optional file attachments. Enter a JSON object (single attachment) or array of JSON objects (multiple), or a process variable that resolves to the same shape.

  Each attachment requires:

  * `path` — file storage key (for example, `flowx-document-plugin-.../file.pdf`), not a local OS path
  * `filename` — name shown to the recipient

  **Example:**

  ```json theme={"system"}
  [{"path": "flowx-document-plugin-.../report.pdf", "filename": "Report.pdf"}]
  ```

  <Frame>
    ![Attachments field example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/attachments.png)
  </Frame>

  <Warning>
    On SMTP, omitting `filename` results in an unnamed attachment. Always set it.
  </Warning>
</ParamField>

<ParamField type="string | array">
  The recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.
</ParamField>

<ParamField type="string | array">
  CC recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.
</ParamField>

<ParamField type="string | array">
  BCC recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.
</ParamField>

<ParamField type="object">
  Map data sent from the process through the template. Use the JSON editor to define key-value pairs matching the data model in your notification template.
</ParamField>

<Frame>
  ![Send Notification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/et2.png)
</Frame>

***

## Example: Reply to a customer email

This example shows a complete flow where an incoming email triggers a process, and the process replies to the sender.

<Steps>
  <Step title="Set up the Email Trigger">
    Configure an [Email Trigger](../../platform-deep-dive/integrations/email-trigger) data source to monitor incoming emails (for example, `support@company.com`).
  </Step>

  <Step title="Set up the Email Sender">
    Configure an [Email Sender](../../platform-deep-dive/integrations/email-sender) data source with SMTP credentials for outbound emails.
  </Step>

  <Step title="Create a notification template">
    Create a notification template for the reply email:

    1. Set **Email Server** to **Predefined Email Connection**
    2. Set **Email Sender** to your Email Sender data source
    3. Design the reply content using the template editor
  </Step>

  <Step title="Design the process">
    Create a process with:

    * A **Message Start Event** configured with the Email Trigger
    * Processing nodes for your business logic (for example, classify the email, look up customer data)
    * A node with the **Send Notification** action configured in reply mode
  </Step>

  <Step title="Configure the Send Notification action">
    On the appropriate node:

    1. Set **Action type** to **Send Notification**
    2. Select your notification template
    3. Toggle **Reply to received emails** to **ON**
    4. Set **Reply to Email Header** to the process variable containing the original email's header params (for example, `${replyField}`)
    5. Set **Receivers** to `${emailMessage.sender}`
    6. Set **Language** to the appropriate language code (for example, `en`)
  </Step>
</Steps>

When an email arrives, the process starts automatically, runs your business logic, and sends a reply to the original sender — maintaining the email conversation thread.

***

## Related resources

<CardGroup>
  <Card title="Email Sender" icon="envelope" href="../../platform-deep-dive/integrations/email-sender">
    Configure SMTP connections for sending emails
  </Card>

  <Card title="Email Trigger" icon="envelope-open-text" href="../../platform-deep-dive/integrations/email-trigger">
    Configure IMAP connections to trigger processes from incoming emails
  </Card>

  <Card title="Notification Templates" icon="file-lines" href="../../platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates">
    Create and manage email notification templates
  </Card>

  <Card title="Node Actions" icon="bolt" href="./actions">
    Learn about all available action types
  </Card>
</CardGroup>


# Start integration workflow action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-integration-workflow

The Start Integration Workflow action initiates a configured workflow to enable data processing, transformation, or other tasks across connected systems.

<Info>
  The Start Integration Workflow action is available on **Send Message Task**, **Task**, and **User Task** nodes within BPMN processes.
</Info>

## Overview

The Start Integration Workflow action allows a BPMN process to trigger an integration workflow, send input data, and receive the workflow output at a designated result key. This enables processes to delegate data fetching, transformations, and external system integrations to lightweight workflows without creating subprocesses.

<Tip>
  For triggering workflows from **UI Flows** (without a BPMN process), see the [Start Workflow action](../ui-flows#configuring-the-start-workflow-action).
</Tip>

***

## How it works

When a Start Integration Workflow action is triggered:

<Steps>
  <Step title="Input data is sent">
    The input data mapped in the action configuration is sent as start variables to the workflow.
  </Step>

  <Step title="Workflow executes">
    The integration workflow runs with the provided inputs, executing its configured nodes (REST calls, data transformations, AI operations, etc.).
  </Step>

  <Step title="Output is captured">
    Workflow output data is captured on the specified result key in the process instance upon completion.
  </Step>

  <Step title="Process continues">
    The BPMN process continues to the next node after the workflow completes.
  </Step>
</Steps>

<Warning>
  The process waits for the workflow to complete before continuing. To receive output data, you must add a **Receive Message Task** node after the Send Message Task that triggers the workflow.
</Warning>

***

## Configuration

### Selecting a workflow

The **Select Workflows** dropdown displays:

* All workflows within the current application version
* Any workflows referenced in the application (e.g., via the Library)

### Input mapping

Map process variables to workflow input parameters:

```json theme={"system"}
{
  "customerId": "${processInstanceData.customer.id}",
  "requestType": "credit_check"
}
```

### Result key

Configure the **result key** where workflow output data will be stored in the process instance variables after completion.

### Receiving output

To capture workflow output in your process:

1. Add a **Receive Message Task** node after the node with the Start Integration Workflow action
2. The workflow output is automatically mapped to the configured result key
3. Subsequent nodes can access the output data via the result key path

***

## When to use

| Scenario                                       | Recommended Action         |
| ---------------------------------------------- | -------------------------- |
| Call external APIs and return data             | Start Integration Workflow |
| Run data transformations                       | Start Integration Workflow |
| Execute AI operations (extraction, generation) | Start Integration Workflow |
| Multi-step user journeys                       | Use subprocesses instead   |
| Processes requiring state management           | Use subprocesses instead   |

***

## Related resources

<CardGroup>
  <Card title="Passing data between nodes" icon="arrow-right-arrow-left" href="../process/passing-data-between-nodes">
    How node outputs land in process variables and how downstream nodes read them
  </Card>

  <Card title="Integration Designer" icon="plug" href="../../platform-deep-dive/integrations/integration-designer">
    Build and configure integration workflows
  </Card>

  <Card title="UI Flows - Start Workflow" icon="play" href="../ui-flows#configuring-the-start-workflow-action">
    Trigger workflows from UI Flows without BPMN processes
  </Card>

  <Card title="Message Events" icon="envelope" href="../node/message-events/message-events">
    Learn about Send and Receive Message Task nodes
  </Card>

  <Card title="Actions Overview" icon="bolt" href="./actions">
    Explore all available action types
  </Card>
</CardGroup>


# Start new project instance
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-new-project-instance

Initiate a new main process from within an ongoing process to handle isolated use cases across different apps or environments.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)
</Frame>

### 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.

<Info>
  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.
</Info>

***

## Common use cases

This action is particularly useful when multiple use cases are managed separately and require isolation between applications. For example:

1. **Customer Profile Management:**
   * Onboarding a power of attorney.
   * Submitting a mortgage request.
   * Enrolling in a credit card program.
     Each of these processes may be managed by different teams and applications, emphasizing the need for separation and flexibility.

2. **Cross-Application Workflow Initiation:**
   A process in one application might require triggering a process in another application with specific parameters. For instance:
   * Initiating an "Onboarding" process (version 2) for a customer directly from the main application.

## Configuring the action

The **Start New Project Instance** action is configured via the **FlowX.AI Designer**. To set it up, navigate to the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-a-new-node).

### Configuration options

#### Action settings

* **Name:** Used internally to distinguish actions on nodes. It’s recommended to define a naming standard for easier identification.
* **Order:** If multiple actions exist on the same node, specify the order in which they run.
* **Timer Expression:** Adds a delay to the action if needed. Use the [**ISO 8601 duration format**](https://www.w3.org/TR/NOTE-datetime) (e.g., `PT30S` for a 30-second delay).
* **Action Type:** Must be set to **Start New Project Instance**.
* **Trigger Type:** Always set to **Manual**.
* **Required Type:**
  * **Mandatory:** Required for automatic actions.
  * **Optional or Mandatory:** Can be used for manual actions.
* **Repeatable:** Check this box if the action can be triggered multiple times.
* **Autorun Children:** Automatically runs child actions (mandatory and automatic) immediately after the parent action completes.
* **Allow Back on This Action:** Enables users to move back in the process flow and redo previous actions. For details, see [Moving a Token Backwards in a Process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process).

<Info>
  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.
</Info>

#### 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-22%20at%2013.36.55.png)
</Frame>

***

## Key benefits

* **Isolated Process Management:** Supports launching new, isolated processes in separate applications, ensuring flexibility and independence across teams and environments.
* **Active Version Execution:** Ensures that the project instance uses the active build version at the time of initiation, providing consistency in functionality.
* **Parameter Passing:** Enables data transfer between the initiating and target processes, improving operational efficiency.


# Start subprocess action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-subprocess-action

A Start subprocess action is an action that allows you to start a subprocess from another (parent) process.

<Info>
  The "Start subprocess" is available only on [User Task](../node/user-task-node) nodes.
  For any other scenarios, you should use the [Call Activity node](../node/call-subprocess-tasks/call-activity-node) instead.
</Info>

Using **subprocesses** is a good way to split the complexity of your business flow into multiple, simple and reusable processes.

<Tip>
  Before configuring a Start subprocess action, read [Process design principles](../process/design-principles) for the rules on when to start a subprocess from a User Task action (must be optional, modal-only navigation) and how it differs from a Call Activity.
</Tip>

## Configuring a Start subprocess action

To use a process as a [subprocess](../process/subprocess) you must first create it. Once the subprocess is created, you can start it from another (parent) process. To do this, you will need to add a **Start Subprocess** action to a [**User task**](../node/task-node) node in the parent process or by using a [Call activity node](../node/call-subprocess-tasks/call-activity-node).

Here are the steps to start a subprocess from a parent process:

1. First, create a [process](../process/process-definition) designed to be used as a [subprocess](../process/subprocess).
2. In the parent process, create a **user task** node where you want to start the subprocess created at step 1.
3. Add a **Start subprocess** action to the task node.
4. Configure the **Start Subprocess** action and from the dropdown list choose the subprocess created at step 1.

By following these steps, you can start a subprocess from a parent process and control its execution based on your specific use case.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/process_subprocess1.png)

The following properties must be configured for a **Start subprocess** action:

* [Action Edit](#action-edit)
* [Trigger](#trigger)
* [Execution](#execution)
* [Navigation](#navigation)
* [Select Subprocess](#select-subprocess)
* [Subprocess Options](#subprocess-options)
* [Data Mapping](#data-mapping)
* [Advanced Configuration](#advanced-configuration)
* [Data to send (for Manual actions)](#data-to-send)

### Action edit

* **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Action type** - should be set to **Start Subprocess**

### Trigger

* **Manual** - toggle to choose if this action should be triggered manually (triggered by the user) or automatically (when the process flow reaches this step). In most use cases, this will be set to automatic
* **Repeatable** - toggle to enable if the action can be triggered multiple times

### Execution

* **Optional** - automatic actions are mandatory by default. Manual actions can be set as optional by enabling this toggle
* **Autorun Children?** - when this is enabled, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized

### Navigation

* **Allow back to this action** - enables back-in-process functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [**Moving a token backwards in a process**](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) section

### Select Subprocess

* **Subprocess name** - dropdown to select the process that you want to start as a subprocess. The dropdown displays the available subprocesses in the format `[Workspace]ProcessName`
* **Branch** - a dropdown menu displaying available branches on the subprocess (both opened and merged)
* **Version** - the type of version that should be used within the subprocess

<Info>
  - **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.
</Info>

### Subprocess Options

* **Parallel Multi-Instance** - enables the subprocess to run multiple instances in parallel
* **Start Async** - when enabled, the subprocess will start asynchronously

### Data Mapping

* **Switch to legacy mapping** - toggle to enable legacy data mapping configuration

When legacy mapping is enabled, you can configure:

* **Copy from current state** - if a value is set here, it will overwrite the default behavior (of copying the whole data from the subprocess) with copying just the data that is specified (based on keys). Click the **+** button to add keys and specify the **Output Key** for each
* **Exclude from current state** - specify which fields you want to exclude when copying the data from the parent process to the subprocess (by default all data fields are copied). Click the **+** button to add keys to exclude

<Info>
  Map which data will be sent and received from the subprocess you are starting.
</Info>

![Start Subprocess Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_subprocess_action_config.png)

### Advanced configuration

* **Show Target Process** - toggle to enable the subprocess to communicate with the parent process (the process where this action is configured)

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [**User task configuration**](../node/user-task-node) section)

<Warning>
  **Data to send** option is configurable only when the action **trigger type** is **Manual**.
</Warning>

## Example

Let's create a main **process**, in this process we will add a user task node that will represent a menu page. In this newly added node we will add multiple subprocess actions that will represent menu items. When you select a menu item, a subprocess will run representing that particular menu item.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_menu1.png)

To start a subprocess, we can, for example, create the following minimum configuration in a user task node (now we configure the process where we want to start a subprocess):

* **Action** - `menu_item_1` - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Trigger type** - Manual; Optional
* **Repeatable** - yes
* **Subprocess** - `docs_menu_item_1` - the name of the process that you want to start as a subprocess
* **Exclude from current state** - `test.price` - copy all the data from the parent, except the price data
* **Copy from current state** - leave this field empty to copy all the data (except the keys that are specified in the **Exclude from current state** field), if not, add the keys from which you wish to copy the data

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_example2.png)

**Advanced configuration**

* **Target process (parentProcessInstanceId)** - `${processInstanceId}` - current process ID

#### Result

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/subprocess_example.gif)


# Upload file action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/upload-file-action

An Upload File action is an action type that allows you to upload a file to a service available on Kafka.

**Why is it useful?** The action will receive a file (or multiple files) from the frontend and send it to Kafka, and will also attach some metadata.

The Upload File action supports two modes:

<CardGroup>
  <Card title="Single file" icon="file">
    Used with the [File Upload Button](../ui-designer/ui-component-types/buttons#file-upload-button). The SDK sends a single temp file ID (`{actionName}TempFileId`).
  </Card>

  <Card title="Multiple files" icon="files">
    Used with the [Multiple File Upload](../ui-designer/ui-component-types/multiple-file-upload) component. The SDK sends a list of temp file IDs (`{actionName}TempFileIds`).
  </Card>
</CardGroup>

The process engine automatically detects which mode to use based on the parameter key present in the process instance data.

## Configuring an Upload file action

Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure an Upload File action, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node), which has the following configuration options:

* [Action Edit](#action-edit)
* [Back in steps (for Manual actions)](#back-in-steps)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)
* [UI Configuration](#ui-configuration)

### Action edit

* **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Order** - if multiple actions are defined on the same node, the running order should be set using this option
* **Timer expression** - it can be used if a delay is required on that action. The format used for this is [ISO 8601 duration format ](https://www.w3.org/TR/NOTE-datetime)(for example, a delay of 30 seconds will be set up as `PT30S`)
* **Action type** - should be set to **Upload File**
* **Trigger type** (options are Automatic/Manual) - choose if this action should be triggered automatically (when the process flow reaches this step) or manually (triggered by the user); in most use cases, this will be set to automatic
* **Required type** (options are Mandatory/Optional) - automatic actions can only be defined as mandatory. Manual actions can be defined as mandatory or optional.
* **Repeatable** - should be checked if the action can be triggered multiple times
* **Autorun Children** - when this is switched on, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/upload_file_action_edit.png)

### Back in steps

* **Allow BACK on this action** - back in process is a functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) section.

### Parameters

* **Address** - the Kafka topic where the file will be posted
* **Document Type** - other metadata that can be set (useful for the [document plugin](../../../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification))
* **Folder** - allows you to configure a value by which the file will be identified in the future
* **Advanced configuration (Show headers)** - this represents a JSON value that will be sent on the headers of the Kafka message

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User Task configuration](../node/user-task-node) section)

<Warning>
  **Data to send** option is configurable only when the action **trigger type** is **Manual**.
</Warning>

## UI configuration

When configuring the event handler that corresponds to the Upload File node action, you must set the **Action Type** to **Upload**. This ensures proper integration between the frontend interface and the backend upload functionality.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_action_upload.png)
</Frame>

***

## Single vs. multi-file processing

When the Upload File action executes, the process engine checks for two mutually exclusive parameter keys:

| Key pattern               | Type                       | Behavior                                                                      |
| ------------------------- | -------------------------- | ----------------------------------------------------------------------------- |
| `{actionName}TempFileId`  | `String` (single UUID)     | **Single-file path** — sends a `DocumentPayload` to Kafka (existing behavior) |
| `{actionName}TempFileIds` | `List<String>` (UUID list) | **Multi-file path** — sends a `BulkDocumentPayload` to Kafka                  |

If neither key is present, the action returns an error and no Kafka message is published.

### Multi-file Kafka topics

When the multi-file path is triggered, the following dedicated Kafka topics are used:

| Direction                        | Topic pattern                                   | Description              |
| -------------------------------- | ----------------------------------------------- | ------------------------ |
| Process engine → document plugin | `plugin.document.trigger.persist.document.bulk` | Bulk persist request     |
| Document plugin → process engine | `plugin.document.persist.document.bulk.results` | Per-file persist results |

### Multi-file request payload

```json theme={"system"}
{
  "documents": [
    {
      "tempFileId": "550e8400-e29b-41d4-a716-446655440000",
      "customId": "119246",
      "documentType": "CONTRACT",
      "shouldOverride": false
    },
    {
      "tempFileId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "customId": "119246",
      "documentType": "CONTRACT",
      "shouldOverride": false
    }
  ]
}
```

<Note>
  `shouldOverride` is always `false` for multi-file uploads. All files share the same `customId` and use `documentType` from the action configuration (typically `BULK`). This means files accumulate — re-uploading adds new documents rather than replacing existing ones.
</Note>

### Partial success handling

The document plugin processes each file individually. If one file fails, the remaining files continue processing — successfully persisted files are not rolled back. The response includes a per-file status so your process logic can handle partial failures.

***

## Example: single file upload

An example of **Upload File Action** is to send a file to the [document plugin](../../../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification). In this case, the configuration will look like this:

**Parameters configuration**

* **Address (topicName)** - will be set to (the id of the document plugin service) `ai.flowx.in.document.persist.v1`
* **Document Type** - metadata used by the document plugin, here we will set it to`BULK`
* **Folder** - the value by which we want to identify this file in the future (here we use the **client.id** value available on the process instance data: `${application.client.id}`

**Advanced configuration**

* **Headers** - headers will send extra metadata to this topic -`{"processInstanceId": ${processInstanceId}, "destinationId": "currentNodeName"}`)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/upload_file_action_params.png)

***

## Academy courses

<CardGroup>
  <Card title="Upload and Preview Files course" icon="graduation-cap" href="https://academy.flowx.ai/explore/upload-and-preview-files">
    Hands-on course covering data stream topics, upload actions, and file preview UI elements
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**uploadFilePreview**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/c0352c70-947e-4276-bd13-bb5cad2b547d/config/2457e456-2219-463c-af30-b92fe19c7703/processes) project for a working file upload and preview implementation.
</Tip>


# Call activity node
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/call-subprocess-tasks/call-activity-node

The Call Activity node is a custom node type in the main process that provides advanced options for starting subprocesses.

There are cases when extra configuration is needed on certain nodes to enhance process management and execution.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/call_activity1.png)
</Frame>

<Card title="Subprocess" href="../../process/subprocess" icon="link" />

<Tip>
  For when to use a Call Activity vs. starting a subprocess from a User Task action, mobile back-navigation behavior, and async mode constraints, see [Process design principles](../../process/design-principles).
</Tip>

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.

<Info>
  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.
</Info>

* **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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sync_async.png)
</Frame>

## Starting multiple subprocesses

### Parallel multi-instance

The Call Activity node can also be used for starting a set of subprocesses that will be started and run at the same time.

This is useful when there is an array of values in the parent process parameters, and a subprocess needs to be started for each element in that array.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/call_activity_parallel_multi_instance.png)
</Frame>

#### Configuration options

When configuring parallel multi-instance on a Call Activity node, you have access to the following configuration options:

* **Input Array**: Declare the array used for subprocess input. Map the array of objects or the keys inside the array of objects to the destination object or its keys from the subprocess.
* **Output Array**: Declare the array used for subprocess output. Map from the subprocess object back to an array of objects in the parent process.
* **Correlation attribute**: The attribute that will be used to correlate subprocess results with parent process data.

#### Data mapping

In the **Data Mapping** section, when **Parallel Multi-instance** is enabled, you can configure:

##### New data mapping

1. **Declare arrays**: Define the arrays used for subprocess input and subprocess output
2. **Input mapping**: In the mapping modal, map the array of objects or the keys inside the array of objects to the destination object or its keys from the subprocess
3. **Output mapping**: Map from the subprocess object back to an array of objects in the parent process

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pmi_mapping.png)
</Frame>

##### Legacy mapping

Legacy mapping works using current mechanics in both configuration and runtime, with no changes to existing features.

<Warning>
  When you change the arrays in the node configuration and save, any existing mappings for input and output will be automatically deleted.
</Warning>

<Tip>
  To filter, reshape, or compute over an array inside a mapping (instead of passing it through wholesale), switch the parameter to **function mode** with the **f(x)** icon and use JavaScript on the resolved value. See [Transforming arrays](../../process/data-mappers#transforming-arrays) on the Data mappers page for patterns and the `|| []` fallback.
</Tip>

#### Correlation attribute behavior

When results from parallel subprocesses are returned, the **correlation attribute** determines how the subprocess payload is handled:

* **Update existing element**: When the correlation attribute value from the subprocess payload matches one or more elements in the parent process array, those elements are updated with the subprocess payload
* **Insert new element**: When the correlation attribute value from the subprocess payload doesn't match any records in the parent process array, the payload is inserted as a new element in the array

This allows for flexible data handling where subprocesses can either update existing records or add new ones based on the correlation logic.

#### Dismissing unfinished subprocesses

When subprocesses are started in **Sync mode**:

* If the token is advanced due to another action being performed in the process
* Then the subprocesses that haven't finished are automatically dismissed

This ensures that the parent process can continue without waiting indefinitely for subprocesses that may not complete.

### Business rule example

Below is an example of an MVEL business rule used to generate a list of shipping codes:

```java theme={"system"}
import java.util.*;

def mapValues(shippingCode) {
    return {
        "shippingCode": shippingCode
    }
}

shippingCodeList = [];

shippingCodeList.add(mapValues("12456"));
shippingCodeList.add(mapValues("146e3"));
shippingCodeList.add(mapValues("24356"));
shippingCodeList.add(mapValues("54356"));
output.put("shippingCodeList", shippingCodeList);
```

In this example, the shippingCodeList array contains multiple shipping code maps. Each of these maps could represent parameters for individual subprocesses. The ability to generate and handle such arrays allows the system to dynamically start and manage multiple subprocesses based on the elements in the array, enabling parallel processing of tasks or operations.

To achieve this, select the *parallel multi-instance* option. The *input array* name from the parent process also needs to be specified.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/input_array.png)
</Frame>

<Info>
  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.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/map_new_list.png)
</Frame>

#### Subprocess business rule example

Here's an MVEL business rule for a subprocess that processes shipping codes:

```java theme={"system"}
import java.util.*;

map = new HashMap();

if (input.item.shippingCode.startsWith("1")) {
    map.package = "Fragile";
} else {
    map.package = "Non-fragile";
}

map.shippingCode = input.item.shippingCode;

output.put("result", map);
```

## Result (one of the subprocess instances)

The result shows the output of a process that has handled multiple shipping codes. The structure is:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/map_new_result.png)
</Frame>

```json theme={"system"}
{
    "package": "Non-fragile",
    "shippingCode": "54356"
}
```

This contains the result of processing the specific shipping code, indicating additional attributes related to the shipping code (for example, package type) determined during the subprocess execution.


# Start embedded subprocess
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/call-subprocess-tasks/start-embedded-subprocess

The Start Embedded Subprocess node initiates subprocesses within a parent process, allowing for encapsulated functionality and enhanced process management.

## Overview

The Start Embedded Subprocess node enables the initiation of subprocesses within a parent process, offering a range of features and options for enhanced functionality.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/start_embedded_subprocess.png)
</Frame>

## 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).

<Warning>
  Embedded subprocesses cannot support multiple swimlanes in the actual implementation.
</Warning>

## Example

Let's explore this scenario: Imagine you're creating a process that involves a series of steps, each akin to a sequential movement of a stepper. Now, among these steps, rather than configuring one step from scratch, you can integrate a pre-existing process, treating it as a self-contained unit within the overarching process.

### Step 1: Design the Embedded Subprocess

<Steps>
  <Step title="Access FlowX.AI Designer">
    Log in to the FlowX.AI Designer where you create and manage process flows.
  </Step>

  <Step title="Create a New Process">
    Start by creating a new process or selecting an existing process where you want to embed the subprocess.
  </Step>

  <Step title="Navigation Areas">
    Design your navigation areas to match your needs.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/embedded_example_copy.png)
    </Frame>

    <Check>
      Make sure you allocated all your user tasks into the navigation area accordingly.
    </Check>
  </Step>

  <Step title="Design Subprocess">
    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**.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/subprocess_to_embed.png)
</Frame>

<Warning>
  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.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/embed_sbprc.gif)
  </Frame>

  <Check>
    Make sure you allocated all your user tasks into the navigation area accordingly.
  </Check>
</Warning>

### Step 2: Configure Start Embedded Subprocess Node

<Steps>
  <Step title="Add Start Embedded Subprocess Node">
    Within the parent process, add a **Start Embedded Subprocess Node** from the node palette to initiate the embedded subprocess.

    <Frame>
      <img alt="Subprocess Nodes" />
    </Frame>
  </Step>

  <Step title="Specify Subprocess">
    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.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/config_embed_node.png)
    </Frame>
  </Step>
</Steps>

### Step 3: Customize Subprocess Behavior

<Info>
  [**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.
</Info>

<Steps>
  <Step title="Customize Data Handling">
    Within the subprocess, handle data as needed. Remember that data is stored within the parent process instance when using embedded subprocesses.
  </Step>

  <Step title="Implement Boundary Events">
    Implement boundary events within the subprocess if specific actions need to be triggered based on certain conditions.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/subprocess_instance.gif)
</Frame>

### Step 4: Test Integration

<Steps>
  <Step title="Test Functionality">
    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.
  </Step>

  <Step title="Verify Data Flow">
    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.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/final_embed_result.gif)
</Frame>

For further details on other ways of configuring and utilizing subprocesses, refer to the following resources:

<CardGroup>
  <Card title="Subprocess Configuration" href="../../process/subprocess" icon="link" />

  <Card title="Start Subprocess action" href="../../actions/start-subprocess-action" icon="link" />

  <Card title="Process design principles" href="../../process/design-principles" icon="compass">
    Subprocess lifecycle, Call Activity vs. User Task action, async constraints.
  </Card>
</CardGroup>


# Error events
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/error-events

Error Events expand the capabilities of process modeling and error handling within BPMN processing. These Error Event nodes enhance the BPMN standard and offer improved control over error management.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_events.png)
</Frame>

## Intermediate event - error event (interrupting)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/error_event.png#center)
</Frame>

## 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

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_scenario.png)
</Frame>

* **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

<Info>
  To draw a sequence from an error event node and link it to other nodes, follow these steps: right-click on the node, and then select the option to "Add Sequence."
</Info>

<Info>
  When crafting a condition, use a predefined key as illustrated below:

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/scenario_input.gif)
  </Frame>

  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`.
</Info>

* **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.

<Info>
  * `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.
</Info>

### 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.

<Check>
  In this scenario we will create a process to throw an error if an email address is not valid.
</Check>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_execution.png)
</Frame>

#### Example configuration

1. **Error Boundary Event:** We will set an error boundary event associated with a user task.

2. **Error Node:** The node will be responsible to redirect the user to other flows after the user's email address is validated based on the conditions defined.

```java theme={"system"}
input.application.client.contactData.email.emailAddress  !=  "john.doe@email.com"
```

<Info>
  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.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_val_v1.png)
  </Frame>
</Info>

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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/error_email.gif)
</Frame>

***

## Academy courses

<CardGroup>
  <Card title="Debug 101 course" icon="graduation-cap" href="https://academy.flowx.ai/explore/debug-your-process-0">
    Learn exception handling, process/token status, error types, and debugging patterns
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**Academy\_Throw\_catch**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/489ac77b-3ba0-444a-b9c8-2a5ffee26492/config/83a4647b-619d-4ddc-87cf-e04d03b6e1d2/processes) and [**errorMessage**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/870d5a68-d770-44b1-a428-4dafa4c361d3/config/c77f6db9-4e30-4f4c-bfab-3ee22e265e5d/processes) projects for working examples of error handling patterns.
</Tip>


# Exclusive gateway
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/exclusive-gateway-node

In the world of process flows, decisions play a crucial role, and that's where the Exclusive Gateway comes into play. This tool enables you to create conditional pathways based on data provided.

## Understanding Exclusive (XOR) Gateway

An exclusive gateway (also called XOR gateway) represents a decision point in your process where exactly one outgoing path is selected based on conditions. This is one of the most common routing mechanisms used in business process modeling.

**Core principles of Exclusive Gateways**

When designing decision logic with exclusive gateways, consider these guiding principles:

<AccordionGroup>
  <Accordion title="Exclusive Choices - Only One Path">
    An exclusive gateway evaluates multiple conditions, but only **one outgoing sequence flow** will be taken - the first condition that evaluates to *true*.
  </Accordion>

  <Accordion title="Condition Evaluation - Logic Drives Flow">
    Each outgoing path from an XOR gateway depends on a condition that evaluates to *true* or *false*.
  </Accordion>

  <Accordion title="Condition Compatibility - Avoid Overlap">
    Overlapping conditions - where multiple paths could match - can lead to **unpredictable routing**. Gateways will select the first matching path, which might not be the correct one.
  </Accordion>

  <Accordion title="Which Path Should Be Taken?">
    This is the essential question behind every XOR gateway: **"Given the input, which path should the process follow?"**
  </Accordion>

  <Accordion title="Testing and Validation - Prove It Works">
    Before deploying a process with an XOR gateway, test it using **realistic data sets** and **edge cases**. Ensure each possible path behaves as expected - and none are silently skipped or broken.
  </Accordion>

  <Accordion title="Decision Points - Clear Divergence">
    Every XOR gateway introduces a **decision point**. Each outgoing sequence flow represents a **distinct outcome** - make sure those outcomes are meaningful and necessary.
  </Accordion>

  <Accordion title="Default Path - Don't Leave the Process Hanging">
    Include a **default path** in the gateway to catch any scenario where none of the defined conditions match. This is especially important when the decision logic depends on external or dynamic data.
  </Accordion>

  <Accordion title="Clear Logic - Keep It Understandable">
    Your conditions should be **simple, explicit, and named clearly**. Avoid nesting complex expressions directly in the gateway when possible - move logic to a service task if needed.
  </Accordion>

  <Accordion title="Maintainability - Keep Logic Aligned with Reality">
    Business rules change. Processes evolve. If your gateway logic doesn't keep up, the process will drift out of sync with how the business actually works.
  </Accordion>
</AccordionGroup>

## Configuring an Exclusive Gateway node

<Frame>
  ![Exclusive gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_exclusive.png#center)
</Frame>

To configure this node effectively, it's essential to set up both the **input** and **output** sequences within the gateway process.

<Frame>
  ![Exclusive Gateways single](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_single.png)
</Frame>

<Frame>
  ![Exclusive Gateways multiple](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_multiple.png)
</Frame>

### 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.

<Info>
  When a step has "Can Go Back" set to false, all preceding steps become inaccessible.
</Info>

* [**Stage** ](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node.

<Frame>
  ![Exclusive gateway configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/excl_gtway.png)
</Frame>

### Gateway decisions

* **Language**: When configuring conditions, you can use JavaScript, Python, MVEL, or Groovy expressions that evaluate to either **true** or **false**.
* **Conditions**: In the **Gateway Decisions** tab, you can see that the conditions (**if, else if, else**) are already built-in and you can **select** the destination node when the condition is **true**.

<Warning>
  The order of expressions matters; the first **true** evaluation stops execution, and the token moves to the selected node.
</Warning>

<Frame>
  ![Exclusive Gateways Decisions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_gateway_decisions.png)
</Frame>

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.

<Frame>
  ![Exclusive Gateways Multiple Flows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_multiple_flows.png)
</Frame>

## JavaScript examples

### Getting input from a Switch UI element

Let's consider the following example: we want to create a process that displays 2 screens and one modal. The gateway will direct the token down a path based on whether a switch element (in our case, VAT) is toggled to true or false.

<Frame>
  ![Exclusive Gateway JavaScript Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_config_example.png)
</Frame>

If, during the second screen, the VAT switch is toggled on, the token will follow the second path, displaying a modal.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/vat_on.gif)
</Frame>

After interacting with the modal, the token will return to the main path, and the process will continue its primary flow.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_flow.png)
</Frame>

**Example configuration**:

* **Language**: JavaScript
* **Expression**:

```javascript theme={"system"}
input.application.company.vat == true // you can use the same method to access a value for other supported scripts in our platform: MVEL, Python and Groovy
```

<Info>
  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.
</Info>

<Info>
  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)
</Info>

### Getting input from multiple UI elements

Consider another scenario in which the process relies on user-provided information, such as age and membership status, to determine eligibility for a discount. This decision-making process utilizes multiple conditions, and depending on the input, it may either conclude or continue with other flows.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_example_discount.gif)
</Frame>

**Configuration example**:

<Frame>
  ![Exclusive Gateway JavaScript Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_config_example.png)
</Frame>

<Info>
  In our case, the expressions fields will be populated with the `input.application.client.age` and `input.application.client.membership` keys, which correspond to the user input collected on the initial screen.
</Info>

Here's how we've configured the rules for our discount eligibility process:

1. Users under 18 with standard membership are not eligible (redirected to not\_eligible\_modal):
   ```
   input.application.client.age < 18 && input.application.client.membership == "standard"
   ```

2. Users 18 or older with standard membership are not eligible due to membership level (redirected to not\_eligible\_membership):
   ```
   input.application.client.age >= 18 && input.application.client.membership == "standard"
   ```

3. Users 18 or older with gold membership qualify for a discount (redirected to discount\_applied):
   ```
   input.application.client.age >= 18 && input.application.client.membership == "gold"
   ```

4. Users 18 or older with platinum membership also qualify for a discount (redirected to discount\_applied):
   ```
   input.application.client.age >= 18 && input.application.client.membership == "platinum"
   ```

5. Any other combinations are sent to needsValidation for further review.

Each rule uses the logical AND operator (&&) to ensure both conditions must be true for the rule to apply. The rules are evaluated in sequence, and the process follows the path of the first matching rule.

The process is visualized as follows:

<Frame>
  <video />
</Frame>


# Message catch boundary events
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-catch-boundary-event

Trigger interrupting or non-interrupting boundary events on user tasks when an incoming message is received during a process flow.

**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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_boundary_multiple.png)
</Frame>

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

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_interrupting_event.png#center)
</Frame>

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

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/%20message_catch_non_interrupting.png#center)
</Frame>

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

<Info>
  Establishes correlation between the catch event and the corresponding throw event. Selection of the relevant throw event triggers the catch event upon message propagation.
</Info>

* **Correlation Key** - process key used to correlate received messages with specific process instances

<Info>
  The correlation key associates incoming messages with specific process instances. Upon receiving a message with a matching correlation key, the catch event is triggered.
</Info>

* **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

<Info>
  This received data becomes available within the process instance, facilitating further processing or decision-making.
</Info>

## Illustrating boundary events (interrupting and non-interrupting)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/boundary_multiple.png)
</Frame>

**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 smooth account opening experience while handling potential interruptions during activation, and also addresses exceptions through the third lane.


# Message Start Event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-catch-start-event

Start a process instance when a specific message, incoming email, or incoming webhook is received by the Message Start Event node.

**Why this matters:** The Message Start Event allows a process to be triggered and initiated based on the reception of a specific message, an incoming email, or an external webhook request.

## Configuring a message start event

A Message Start Event is a special event in a process that initiates the start of a process instance upon receiving a specific trigger. It acts as the entry point for the process, waiting for the designated trigger to occur. Once triggered, the process instance is created and begins its execution, following the defined process flow from that point onwards.

<Warning>
  To use this type of node with the task management plugin, you must have a service account defined in your identity solution. For more information, see how to [create service accounts using Keycloak](../../../../setup-guides/access-management/configuring-an-iam-solution#process-engine-service-account).
</Warning>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_catch_message_event.png#center)
</Frame>

### General config

<ParamField type="string">
  The name of the node.
</ParamField>

<ParamField type="dropdown">
  Assign a stage to the node, if needed.
</ParamField>

***

### Process trigger

The **Trigger Type** determines how the process instance is started. Four options are available:

<Tabs>
  <Tab title="Internal Throw Message">
    Use this trigger type when you want to start a process instance from another process using a [Message Throw Event](./message-throw-intermediate-event). This is the classic approach for inter-process communication.

    <Frame>
      ![Internal Throw Message configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm3.png)
    </Frame>

    <ParamField type="enum">
      Select **Internal Throw Message** to enable message-based triggering from other processes.
    </ParamField>

    <ParamField type="dropdown">
      The message event name that this start event listens for. This must match the event name configured in the corresponding Message Throw Event from the sending process.
    </ParamField>

    <ParamField type="string">
      The process key / variable name where incoming message data will be mapped in the started process. The data sent from the throwing process will be available under this key.
    </ParamField>

    <Info>
      **Note:** The correlation key field is not available for Message Start Events. Correlation keys are only used for intermediate catch events where a running process instance needs to be identified. For start events, a new process instance is always created.
    </Info>
  </Tab>

  <Tab title="Email Trigger">
    Use this trigger type when you want to automatically start a process instance when an email is received. This requires an Email Trigger data source to be configured in Integration Designer.

    <Frame>
      ![Email Trigger configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm1.png)
    </Frame>

    <ParamField type="enum">
      Select **Email Trigger** to enable email-based process triggering.
    </ParamField>

    <ParamField type="dropdown">
      Choose the Email Trigger data source that will initiate this process. The dropdown displays all Email Trigger resources configured in your application.
    </ParamField>

    <Info>
      Before using Email Trigger, you must configure an Email Trigger data source in Integration Designer. See [Email Trigger](../../../platform-deep-dive/integrations/email-trigger) for complete setup instructions.
    </Info>

    <Tip>
      When an email arrives and triggers the process, the email data (sender, subject, body, attachments, etc.) is automatically mapped to the process instance data. See the [Email Trigger documentation](../../../platform-deep-dive/integrations/email-trigger#email-data-mapping) for the complete data structure.
    </Tip>
  </Tab>

  <Tab title="Microsoft Outlook">
    Use this trigger type when you want to automatically start a process instance when an email is received in a Microsoft Outlook mailbox via the MS Graph API. This requires a Microsoft Outlook data source with **Read** or **Read & Send** scope configured in Integration Designer.

    <ParamField type="enum">
      Select **Microsoft Outlook** to enable Outlook email-based process triggering.
    </ParamField>

    <ParamField type="dropdown">
      Choose the Microsoft Outlook data source that will initiate this process. The dropdown displays all Microsoft Outlook data sources with Read or Read & Send scope configured in your application.
    </ParamField>

    <Info>
      Before using Microsoft Outlook, you must configure a Microsoft Outlook data source in Integration Designer. See [Microsoft Outlook](../../../platform-deep-dive/integrations/microsoft-outlook-data-source) for complete setup instructions.
    </Info>

    <Tip>
      When an email arrives and triggers the process, the email data (sender, subject, body, attachments, headers) is automatically mapped to the process instance data. The `x-ms-graph-message-id` header is included for reply threading. See the [Microsoft Outlook documentation](../../../platform-deep-dive/integrations/microsoft-outlook-data-source#email-data-schema) for the complete data structure.
    </Tip>
  </Tab>

  <Tab title="Incoming Webhook">
    Use this trigger type when you want to start a process instance from an external HTTP POST request. This requires an Incoming Webhook data source to be configured in Integration Designer.

    <Frame>
      ![Incoming Webhook trigger configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_configured.png)
    </Frame>

    <ParamField type="enum">
      Select **Incoming Webhook** to enable webhook-based process triggering.
    </ParamField>

    <ParamField type="dropdown">
      Choose the Incoming Webhook data source that will initiate this process. The dropdown displays all Incoming Webhook resources configured in your project.
    </ParamField>

    <Info>
      Before using Incoming Webhook, you must create an Incoming Webhook data source in Integration Designer. See [Incoming Webhooks](../../../platform-deep-dive/integrations/incoming-webhooks) for complete setup instructions.
    </Info>

    <Tip>
      When a webhook request triggers the process, the payload data (body, headers, timestamp) is automatically mapped to the process instance data. See the [Incoming Webhooks documentation](../../../platform-deep-dive/integrations/incoming-webhooks#webhook-payload) for the complete data structure.
    </Tip>
  </Tab>
</Tabs>

<Warning>
  When switching between trigger types in the Designer UI, the configuration fields are automatically cleared to prevent invalid configurations. Ensure you reconfigure all required fields after changing the trigger type.
</Warning>

***

## Example: Interprocess communication with internal throw message

This section demonstrates how to use the **Internal Throw Message** trigger type to start a process from another process.

### Throwing process (sender)

The throwing process contains a [Message Throw Event](./message-throw-intermediate-event) that sends a message to start the target process.

<Frame>
  ![Throwing process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm4.png)
</Frame>

#### Configuring the throw intermediate event

<ParamField type="dropdown">
  The message event name. This must match the **Correlate with throwing message events** value configured in the target Message Start Event.
</ParamField>

<ParamField type="string">
  Define a JSON structure with the data to be sent along with the message. For example:

  ```json theme={"system"}
  {"test": "docs"}
  ```
</ParamField>

<ParamField type="dropdown">
  Assign a stage to the node if needed.
</ParamField>

<Frame>
  ![Throw event configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm7.png)
</Frame>

### Catching process (receiver)

The catching process uses a Message Start Event configured with the **Internal Throw Message** trigger type.

<Frame>
  ![Catching process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm6.png)
</Frame>

#### Configuring the Message Start Event (Start Catch Message) node

<Info>
  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. For more information, see how to [create service accounts using Keycloak](../../../../setup-guides/access-management/configuring-an-iam-solution#process-engine-service-account).
</Info>

<Frame>
  ![Message Start Event (Start Catch Message) node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm5.png)
</Frame>

### Result

After running the throw process, the process containing the Message Start Event (Start Catch Message) node is triggered automatically. The data sent from the throwing process is available in the new process instance:

<Frame>
  ![Message Start Event (Start Catch Message) node result](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm8.png)
</Frame>


# Message Events
Source: https://docs.flowx.ai/5.9/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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_events_new.png)
</Frame>

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 two properties that must match between the throw and catch events:

* **Message name** — configured via the "Correlate with catch/throwing events" dropdown, must be identical on both sides
* **Correlation value** — the runtime value extracted from the correlation key expression

<Info>
  A correlation key is an expression that resolves to a value at runtime. The engine extracts this value from the process instance and uses it to match throw and catch events. It is not the key name that matters, but the **value** it resolves to.

  For example, if two sibling subprocesses both use `parentProcessInstanceId` as their correlation key, the engine extracts the parent's ID from each — since both share the same parent, the values match and the message is delivered.
</Info>

### Available correlation keys

The correlation key expression is evaluated against two sources, checked in order:

1. **Instance metadata** — system properties automatically set by the engine:

| Key                         | Description                                | Available on      |
| --------------------------- | ------------------------------------------ | ----------------- |
| `processInstanceId`         | Numeric ID of the current process instance | All instances     |
| `processInstanceUuid`       | UUID of the current process instance       | All instances     |
| `parentProcessInstanceId`   | Numeric ID of the parent process           | Subprocesses only |
| `parentProcessInstanceUuid` | UUID of the parent process                 | Subprocesses only |

2. **Process variables** (`paramValues`) — any custom variable stored in the process data model (e.g., `orderId`, `applicationId`, `customer.ssn`)

<Tip>
  For communication between sibling subprocesses (subprocess → subprocess), use `parentProcessInstanceId` since both siblings share the same parent. Alternatively, pass a custom business key from the parent process to both subprocesses.
</Tip>

### Timing requirement

<Warning>
  The catch event must be in a **waiting state** (its token must have arrived on the node) **before** the throw event fires. If the throw executes before the catch is ready, the message will not be delivered and correlation will fail.

  When using async subprocesses, ensure the subprocess containing the catch event has enough time to reach the catch node before the throw event is triggered in another subprocess.
</Warning>

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, must be the same for throw and catch events (configured via the "Correlate with" dropdown in the Designer)
* `correlationKey`: an expression that resolves to a value used to match the throw event with the correct catch event instance
* `data`: allows defining the JSON message body mapping as output and input

### Data example

```json theme={"system"}
{
	"document":{
			"documentId": "${document.id}",
			"documentUrl": "${document.url}"
	}
}
```


# Intermediate message events in business processes
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/example-intermediate-message-events

Orchestrate information exchange and synchronize stages within a process using Intermediate Message Events.

* [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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_catch_intermediate_process.png)
</Frame>

#### 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 theme={"system"}
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:

<Steps>
  <Step>
    **FlowX.AI Designer**: Open FlowX.AI Designer.
  </Step>

  <Step>
    **Draw BPMN Diagram**: Import the provided BPMN diagram into FlowX.AI Designer or recreate it by drawing the necessary elements.
  </Step>

  <Step>
    **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.
  </Step>

  <Step>
    **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*

    <Tip>
      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.
    </Tip>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task1_interm.gif)
    </Frame>

    * **User Task 2** - *approve\_credit\_card\_request*

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task2_interm.gif)
    </Frame>

    In this screen, we configured a modal to display the approval confirmation. The modal acts as a single brief interruption before the process advances, not as a step in the main flow. See [Process design principles](../../../process/design-principles#modal-design) for when a modal is appropriate.

    * **User Task 3** - *reject\_credit\_card\_request*

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task3_interm.gif)
    </Frame>
  </Step>

  <Step>
    **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.

    <Tip>
      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.
    </Tip>

    <Frame>
      ![MVEL Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/mvel_example_gateway.png)
    </Frame>

    Also, add Parallel gateways to open/close parallel paths.

    <Frame>
      ![Parallel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/parallel_open_close.gif)
    </Frame>
  </Step>

  <Step>
    **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.
  </Step>

  <Step>
    **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.
  </Step>

  <Step>
    **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.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/sending_a_notification.png)
    </Frame>

    Define the content of the rejection letter, the method of notification, and any additional details required for a smooth user experience. More details on how to configure a notification can be found in the following section:

    <Card>
      [**Sending a notification**](../../../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification)
    </Card>
  </Step>

  <Step>
    **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.
  </Step>
</Steps>

### 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_intrmdt.png)
</Frame>

#### 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`

<Info>
  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.
</Info>

* **Correlation Key** — A business or process variable that identifies the target instance. In our example, we used `processInstanceId`, automatically available in instance metadata at runtime.

* **Send data** — Define a JSON structure with the data to transmit alongside the message. In this example, we used dynamic data from user input bound to a slider UI element.

```json theme={"system"}
{"value": "${application.income}"}
```

* **Stage** - Assign a stage to the node.

In the end, this is what we have:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_config.png)
</Frame>

### 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt.png)
</Frame>

#### 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 message events** — Must match the message name configured on the corresponding throw event. In our example: `throwcatchsequenceloan`
* **Correlation Key** — Must resolve to the same value as the throw event's correlation key at runtime.
* **Process Key** — The process key where the data received from the throw event will be stored.
* **Stage** - Assign a stage to the node.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt_cfg.png)
</Frame>

### 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.

<Info>
  We will test the path where the user gets rejected.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/testing_the_proc_interm.gif)
</Frame>

In the end, the user will receive this notification via email:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/notification_received.png)
</Frame>

## 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 theme={"system"}
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)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_and_catch_subpr.png)
</Frame>

<Steps>
  <Step>
    \*\*Open **FlowX.AI Designer** and create a new process.
  </Step>

  <Step>
    **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.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task_loan_subrp.gif)
    </Frame>
  </Step>

  <Step>
    **Integrate a [**Call activity**](../../../node/call-subprocess-tasks/call-activity-node) node**.

    * Add a "Subprocess Run Node" and configure it:

      * **Start Async** - Enable this option. When subprocesses are initiated in async mode, the parent process continues without waiting for completion. The parent process then manages the reception of process data from the child via catch message events.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_run_node_cfg.png)
    </Frame>

    * 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.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_subprocess_configuration.png)
    </Frame>

    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)
  </Step>

  <Step>
    **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** — A business or process variable that identifies the target instance. In our example, we used `processInstanceId`, which is automatically available in instance metadata at runtime.

      * **Send data** — Define a JSON structure with the data to transmit alongside the message. In this example, we used dynamic data from user input bound to slider UI elements.

    ```json theme={"system"}
    {
      "client_details": {
        "clientIncome": ${application.income},
        "loanAmount": ${application.loan.amount},
        "loanTerm": ${application.loan.term}
      }
    }
    ```

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_in_anthr_proc.png)
    </Frame>
  </Step>
</Steps>

### Configuring the subprocess (catch event)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_from_anthr_proc.png)
</Frame>

<Steps>
  <Step title="Insert an Intermediate Message Catch event">
    Configure the node:

    * **Correlate with throwing message events** — Use the same message name added for the associated throw message event.
    * **Correlation Key** — Set to `parentProcessInstanceId`. Since this is a subprocess, the engine extracts the parent's process instance ID, which matches the `processInstanceId` value extracted by the throw event in the parent process.
    * **Process Key** — The process key where the data received from the throw event will be stored.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_interm_from_anthr_prc.png)
    </Frame>
  </Step>

  <Step title="Integrate a Service Task">
    * 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.
  </Step>
</Steps>

***

## Subprocess-to-subprocess communication

Facilitate communication between sibling subprocesses (two subprocesses started from the same parent process) using message intermediate events.

### Business scenario

Consider a process where a parent process starts two subprocesses: one for document verification and another for fraud checks. Once the fraud check subprocess completes its analysis, it sends a message to the document verification subprocess with the results.

```mermaid theme={"system"}
graph TD
  subgraph Parent Process
    a[Start]
    b["Call Activity 1 (async) → Fraud Check"]
    c["Call Activity 2 → Document Verification"]
    d[End]
  end

  subgraph "Subprocess A: Fraud Check"
    e[Start]
    f[Perform Fraud Analysis]
    g["Throw Message (fraud results)"]
    h[End]
  end

  subgraph "Subprocess B: Document Verification"
    i[Start]
    j["Catch Message (wait for fraud results)"]
    k[Continue Verification with Fraud Data]
    l[End]
  end

  a --> b --> c --> d
  e --> f --> g --> h
  i --> j --> k --> l
  g -.->|message| j
```

### Correlation key for sibling subprocesses

Since both subprocesses are started from the same parent, they share the same `parentProcessInstanceId`. Use this as the correlation key on both throw and catch events:

* **Throw event** (in Fraud Check subprocess): **Correlation Key** = `parentProcessInstanceId`
* **Catch event** (in Document Verification subprocess): **Correlation Key** = `parentProcessInstanceId`

At runtime, both resolve to the same value (the parent's process instance ID), so the engine can match them.

<Tip>
  Alternatively, you can pass a custom business key (e.g., `applicationId`) from the parent to both subprocesses and use that as the correlation key.
</Tip>

### Timing: catch must be waiting before throw fires

<Warning>
  The catch event must reach its waiting state **before** the throw event executes. If the throw fires first, there is no registered listener to receive the message and correlation will fail.

  **Common pitfall with async subprocesses:** If Call Activity 1 is set to **Start Async**, it launches Subprocess A without waiting for it to complete, and the parent immediately starts Call Activity 2 (Subprocess B). If Subprocess A reaches its throw event before Subprocess B reaches its catch event, the message is lost.

  **Solutions:**

  * Ensure the subprocess with the **catch** event starts **first** (or has enough lead time to reach the catch node)
  * Add a timer or additional tasks before the throw event to give the catch event time to register
  * Reverse the logic: place the catch in the subprocess that starts first (async), and the throw in the one that starts second
</Warning>

***

### Throw with multiple catch events

<Card title="Throw with multiple catch events example" href="https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Throw%20with%20multiple%20catch%20events.pdf" icon="download">
  Download the example
</Card>


# Message catch intermediate event
Source: https://docs.flowx.ai/5.9/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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_intermediate_event.png#center)
</Frame>

**Why this matters:** 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.

<Info>
  Message Catch Intermediate Event can be used as a standalone node, this means that it will block a process until it receives an event.
</Info>

## 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt.png)
</Frame>

### Trigger type

A message catch intermediate event can be driven by one of two trigger types:

| Trigger type               | Use it when…                                                                                                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Internal Throw Message** | Another node inside FlowX — typically a [Message Throw Intermediate Event](./message-throw-intermediate-event) elsewhere in the process — sends the resume signal.                                                             |
| **Incoming Webhook**       | An external system resumes the process over HTTP. See [Incoming Webhooks → On a Message Catch Intermediate Event](../../../platform-deep-dive/integrations/incoming-webhooks#on-a-message-catch-intermediate-event) for setup. |

The rest of this page covers the **Internal Throw Message** configuration. For the **Incoming Webhook** flow (Data Source, Webhook Correlation Key, Process Correlation Key, Process Key), follow the Incoming Webhooks page.

#### General config

<ParamField type="dropdown">
  Select the throw message event that this catch event should listen for. The dropdown contains all throw messages from the process definitions accessible to the user.

  <Info>
    The message name must match exactly between the throw and catch events for correlation to work.
  </Info>
</ParamField>

<ParamField type="string">
  A business or process variable that uniquely identifies the process instance to which the message is sent.

  The engine extracts the value of this key when the token arrives on the catch node. At runtime, the extracted value must match the value extracted by the corresponding throw event.

  Common correlation key examples:

  * `processInstanceId` — to correlate within the same process
  * `parentProcessInstanceId` — to receive messages from a parent process or to communicate between sibling subprocesses that share the same parent
  * Custom business keys like `orderId`, `applicationId`, etc.
</ParamField>

<ParamField type="string">
  The process key where the data received from the throw event will be stored. This allows the catch event to capture and use the payload sent along with the message.
</ParamField>

<Warning>
  The catch event must be in a **waiting state** before the corresponding throw event fires. If the throw executes before the catch node is reached, the message will not be delivered. This is especially important when working with async subprocesses — ensure the subprocess containing the catch event has time to reach the catch node before the throw fires.
</Warning>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt_cfg.png)
</Frame>


# Message intermediate events overview
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/message-intermediate

Overview of BPMN message intermediate events for throwing and catching messages within process flows.

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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_message_events.png)
</Frame>

### 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.

<Card title="Message Throw Intermediate Event" href="./message-throw-intermediate-event" icon="link" />

### Message catch intermediate event

This event waits for a message to be caught before continuing with the process flow.

<Card title="Message Catch Intermediate Event" href="./message-catch-intermediate-event" icon="link" />


# Message throw intermediate event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/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. It represents the act of throwing a message to initiate a specific task or notification.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/throw_message_event.png#center)
</Frame>

**Why this matters:** The Message Throw Intermediate Event enables communication between different parts of a process or between separate processes entirely. It allows you to send data and trigger actions in other process instances, making it essential for coordinating complex workflows.

## Configuring a message throw intermediate event

A Message Throw Intermediate Event sends a message that can be correlated with a catch event—either a [Message Catch Intermediate Event](./message-catch-intermediate-event) in a running process or a [Message Start Event](../message-catch-start-event) to initiate a new process instance. 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mti2.png)
</Frame>

### General config

<ParamField type="dropdown">
  Select the catch message event that this throw event should communicate with. The dropdown contains all catch messages from the process definitions accessible to the user.

  <Info>
    Define the message for the catch event first. This ensures its availability in the dropdown menu when configuring the throw intermediate event.
  </Info>
</ParamField>

<ParamField type="string">
  A business or process variable that uniquely identifies the instance to which the message is sent. The engine extracts the value of this key at runtime and uses it to find a matching catch event listener.

  Common correlation key examples:

  * `processInstanceId` — to correlate within the same process
  * `parentProcessInstanceId` — to communicate between a parent and subprocess, or between sibling subprocesses that share the same parent
  * Custom business keys like `orderId`, `applicationId`, etc.
</ParamField>

<ParamField type="object">
  Define a JSON structure with the data to be sent along with the message. You can use dynamic values from the process data using the `${}` syntax.

  Example:

  ```json theme={"system"}
  {
    "customerName": "${customer.name}",
    "applicationStatus": "${application.status}",
    "amount": ${application.amount}
  }
  ```
</ParamField>

<ParamField type="dropdown">
  Assign a stage to the node if needed. Stages help organize and track process progress.
</ParamField>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mti1.png)
</Frame>

***

<Warning>
  The corresponding catch event must be in a **waiting state** before this throw event fires. If the throw executes before the catch node is reached, the message will not be delivered and correlation will fail. This is especially important when working with async subprocesses.
</Warning>

## Use cases

### Correlating with a running process instance

Use the Message Throw Intermediate Event to send data to a [Message Catch Intermediate Event](./message-catch-intermediate-event) that is waiting in another part of the same process or in a different running process instance.

<Info>
  Both the throw and catch events must have matching:

  * **Message name** (selected in **Correlate with catch message events** / **Correlate with throwing message events**)
  * **Correlation key value** at runtime
</Info>

### Starting a new process instance

Use the Message Throw Intermediate Event to trigger a [Message Start Event](../message-catch-start-event) and start a new process instance. In this case, no correlation key is needed on the catch side since a new process instance is always created.

<Tip>
  For detailed examples of interprocess communication using throw and catch events, see [Intermediate Message Events Examples](./example-intermediate-message-events).
</Tip>

***

## Related documentation

<CardGroup>
  <Card title="Message Catch Intermediate Event" href="./message-catch-intermediate-event" icon="message">
    Learn how to configure catch events that receive messages from throw events.
  </Card>

  <Card title="Message Start Event" href="../message-catch-start-event" icon="play">
    Trigger new process instances using messages from throw events.
  </Card>

  <Card title="Intermediate Message Events Examples" href="./example-intermediate-message-events" icon="book">
    Complete examples showing throw and catch event configurations.
  </Card>
</CardGroup>


# Send message/receive message tasks
Source: https://docs.flowx.ai/5.9/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 actions or start integration workflow actions.

## Send message task

This node is used to configure messages that should be sent to external systems.

<Frame>
  ![Send Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/send-task_node.svg#center)
</Frame>

### 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 Config

Inside the **General Config** tab, you have the following properties:

* **Node Name**: The name of the node
* [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node

To configure a send message task, you first need to add a new node and then configure an **action** (**Kafka Send Action** or **Start Integration Workflow** type):

<Steps>
  1. Open <Tooltip>**Process Designer** </Tooltip> 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 <Tooltip> **action** </Tooltip>, the type of the action set to **Kafka Send Action** or **Start Integration Workflow**.
  5. A few action parameters will need to be filled in depending on the selected action type.
</Steps>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kafka_send_action.png)

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-project-flow/adding-an-action-to-a-node), use the **Actions** tab at the node level, which has the following configuration sections:

* [Action Edit](#action-edit)
* [Trigger](#trigger)
* [Execution](#execution)
* [Navigation](#navigation)
* [Parameters](#parameters)
* [Advanced configuration](#advanced-configuration)

#### Action Edit

* **Name**: The name of the action
* **Action Type**: The type of the action, should be set to **Kafka Send Action** for actions used to send messages to external systems, or **Start Integration Workflow** to trigger [**workflows**](../../platform-deep-dive/integrations/integration-designer#workflows)

<Info>
  Additional fields like **Order** and **Timer Expression** may also be available in certain configurations to control action execution order and timing.
</Info>

#### Trigger

* **Manual**: When enabled, the action must be triggered manually by the user. When off (automatic), the action triggers automatically when the process flow reaches this step
* **Repeatable**: When enabled, the action can be triggered multiple times

#### Execution

* **Optional**: When enabled, the action is optional and the process can continue without it being executed. When off (mandatory), the action must be completed before advancing to the next node
* **Autorun Children**: When enabled, child actions (defined as mandatory and automatic) run immediately after the parent action completes

#### Parameters

Parameters define the message details for the Kafka send action:

* **Topics**: The Kafka topic name where the message should be sent
* **Message**: The message payload to send (can include process variables using `${variableName}` syntax)

<Info>
  Parameters can be added either using the **Custom** option (where you configure everything on the spot) or by using **From Integration** to import parameters already defined in an integration.

  For more information, see the [Integrations Management documentation](../../platform-deep-dive/integrations/integration-designer).
</Info>

#### Advanced configuration

* **Show Headers**: When enabled, allows you to configure custom headers for the Kafka message (for example, `processInstanceId`)

<Frame>
  ![Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/parameters_message_send.gif)
</Frame>

For more information about Kafka, check the following sections:

<CardGroup>
  <Card title="Intro to Kafka" href="/5.1/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts" icon="link" />

  <Card title="Kafka documentation" href="https://kafka.apache.org/documentation/" icon="link" />
</CardGroup>

### 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`
* **Action Type** - Kafka Send Action

#### Trigger

* **Manual** - off (automatic trigger)
* **Repeatable** - off (it only needs to run once)

#### Execution

* **Optional** - off (mandatory - the action must be completed before advancing to the next node)
* **Autorun Children** - enabled (if there are child actions, they run automatically)

#### Parameters

* **Topics** - `ai.flowx.in.crm.search.v1` - the Kafka topic on which the CRM listens for requests
* **Message**:

```json theme={"system"}
// Example of a message payload
{ "clientType": "${application.client.clientType}", "personalNumber": "${personalNumber.client.personalNumber}" }
```

#### Advanced configuration

* **Show Headers**: When enabled, allows you to configure custom headers for the Kafka message (for example, `processInstanceId`, correlation IDs, or other metadata)

## Receive Message Task

This type of node is used when we need to wait for a reply from an external system.

<Frame>
  ![Receive Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/receive-task%20_node.svg#center)
</Frame>

The reply from the external system will be saved in the process instance values, on a specified key.

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/5.x/receive_kafka.png)

### Configuring a Receive Message Task

The values you need to configure for this node are the following:

### Data stream topics

* **Custom**: You can configure the topic name and key name manually
* **From Workflow**: You can select a workflow from the dropdown list.


# Process nodes (BPMN)
Source: https://docs.flowx.ai/5.9/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.

<Tip>
  For a comprehensive understanding of BPMN (Business Process Model and Notation), start with the following section:
  [**Intro to BPMN**](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn)
</Tip>

The FlowX.AI platform supports various node types, each requiring distinct configurations to fulfill its role in your business flow. Understanding these node types is essential for building effective process workflows.

## Types of BPMN nodes

The following sections explore each type of BPMN node available in FlowX.AI:

### Start and End nodes

* **Start Node**: Defines the beginning of a process flow and how a process instance is initiated.
* **Message Start Event**: Starts a process instance when a specific message is received.
* **Timer Start Event**: Initiates a process instance based on a specified time or schedule.
* **End Node**: Marks where the process finishes.

<Info>
  A process definition may have multiple start nodes (only if they are in different swimlanes, only one start node per swimlane) and end nodes based on the flow outcomes.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_end_nodes.png)
</Frame>

### Activity nodes

* **User Task**: Represents user interactions and displays UI components.

* **Service Task**: Executes tasks using various services to accomplish specific functions.

* **Start Embedded Subprocess**: Initiates subprocesses within a parent process, providing encapsulated functionality and enhanced process management.

* **Call Activity**: Provides advanced options for starting **subprocesses** with enhanced control.

* **Send Message Task**: Sends messages to external systems, integrations, and plugins.

* **Receive Message Task**: Receives messages from external systems, integrations, and plugins.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/activities.png)
</Frame>

### Intermediate events

* **Message Throw Event**: Throws a message and continues with the process flow.
* **Message Catch Event - Interrupting**: Waits for a message before continuing with the process flow.
* **Message Catch Event - Non-Interrupting**: Waits for a message before continuing with the process flow.
* **Timer Event - Interrupting**: Triggers based on a specific time duration, date, or cycle. Can also be used as a boundary event.
* **Timer Event - Non-Interrupting**: Triggers based on a specific time duration, date, or cycle. Can also be used as a boundary event.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intermediate_events.png)
</Frame>

#### 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 Event - Interrupting**: Waits for and responds to a specific incoming message during a task.
* **Message Catch Event - Non-Interrupting**: Waits for and responds to a specific incoming message during a task.
* **Timer Event - Interrupting**: Activates based on elapsed time, a specific date, or a recurring cycle, useful for timeouts or deadlines.
* **Timer Event - Non-Interrupting**: Activates based on elapsed time, a specific date, or a recurring cycle, useful for timeouts or deadlines.
* **Error Event - Interrupting**: This event catches errors during a task or subprocess and redirects the process flow to handle them appropriately.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-03%20at%2012.17.17.png)
</Frame>

### Compatibility matrix

Boundary events can attach to the following node types:

<AccordionGroup>
  <Accordion title="Compatible node types">
    * **User Task**: All boundary event types supported
    * **Service Task**: Supports Message Catch Event - Interrupting, Timer Event - Interrupting, and Error Event - Interrupting boundary events.
    * **Send Message/Receive Message Tasks**: Supports Message Catch Event - Interrupting, Timer Event - Interrupting, and Error Event - Interrupting boundary events.
    * **Start Embedded Subprocess**: Supports Message Catch Event - Interrupting, Timer Event - Interrupting, and Error Event - Interrupting boundary events.
    * **Call Activity**: Supports Message Catch Event - Interrupting/Non-Interrupting, Timer Event - Interrupting/Non-Interrupting, and Error Event - Interrupting boundary events.
  </Accordion>
</AccordionGroup>

Boundary events are a critical element for creating resilient and adaptive processes, enabling efficient error handling, timeout management, and real-time interactions.

## Next steps

Now that you understand the different types of BPMN nodes available in FlowX.AI, you can start building your own processes. Each node type offers specific configuration options and capabilities that you'll explore as you design your workflows.

<Tip>
  Start with simple processes using Start nodes, User Tasks, and End nodes before incorporating more complex elements like boundary events and subprocesses.
</Tip>

For hands-on guidance on creating and configuring nodes in your processes, see:

[Managing a process flow](../../flowx-designer/managing-a-project-flow/adding-a-new-node)

For comprehensive insights into BPMN and its various node types, explore our course at FlowX Academy:

<Card title="BPMN 101" href="https://academy.flowx.ai/explore/bpmn-101" icon="school">
  * What's BPMN (Business Process Model Notation) and how does it work?
  * How is BPMN used in FlowX?
</Card>


# Parallel gateway
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/parallel-gateway

Run independent tasks concurrently in a process by opening and closing a parallel section with Parallel Gateway nodes.

## Configuring parallel paths

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_parallel.png#center)
</Frame>

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/5.9/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.

<Frame>
  ![Start node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/start_node.png#center)
</Frame>

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/5.x/start_node.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)

#### General Config

* **Node name**: The name of the node
* [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node

## End node

<Frame>
  ![End Event](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/end-event.png#center)
</Frame>

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/5.x/end_node.png)


# Service Task node
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/task-node

A service 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.

<Frame>
  ![Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/task_node.png)
</Frame>

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**: Allows users to return to a previous step after completing current step.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/task_node_config.png)
</Frame>

#### Data stream topics

* **From Workflow**: Select a workflow from the dropdown list.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dst_wkflw.png)
</Frame>

* **Custom**: 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)

* **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 the Task Management Plugin to update the information after this node. Update the Base URL, title, stage, priority, or business filters using business rules.

#### Data Search

* **Update data search**: Send updates to the Data Search service after this node, allowing you retrieve data from various process instances.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/update_tm_ds.png)
</Frame>

## 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

<Info>
  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.
</Info>

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. **Action type**: Defines the appropriate action type

3. **Trigger**:
   * **Manual**: manually (triggered by the user)
   * **If switched off**: triggered automatically (when the process flow reaches this step)

4. **Execution**:
   * **Optional**: the action is optional
   * **If switched off**: the action is mandatory

5. **Navigation**:
   * **Allow back to this action**: When turned on, the action can be executed again when the token returned from a downstream node (can be switched on only if the trigger type is **Manual**).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/action_edit.png)
</Frame>

#### Parameters

<Info>
  Depending on the type of the [**action**](../actions/actions), different properties are available. We refer to a **Business rule** as an example
</Info>

1. **Business Rules** - business rules can be attached to a node by using actions with action rules on them, these can be specified using MVEL expressions, or scripts written in Javascript, Python, or Groovy.

<Card title="Supported scripting languages" href="../supported-scripts" icon="link" />

### 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**
* **JavaScript**
* **Python**
* **Groovy**

For more details about node actions, check the following section:

<Card title="Node actions" href="../actions/actions" icon="link" />


# Timer boundary event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-boundary-event

Attach a BPMN event to a task or subprocess that activates when a duration, deadline, or specific date condition is met.

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 incorporated into the overall process design. This capability is especially valuable for scenarios where time-sensitive actions or notifications need to be integrated 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_boundary_event_interrupting.svg#center)
</Frame>

### 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                    |

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_timer_event.png)
</Frame>

### 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_boundary_event_non_interrupting.svg#center)
</Frame>

### 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/5.9/docs/building-blocks/node/timer-events/timer-events

Trigger BPMN actions or events at predefined intervals, durations, or cycles to add time-based behavior to processes.

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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-03%20at%2014.37.56.png)
</Frame>

## 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

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_events_duration_date.gif)
</Frame>

* **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

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_start_cycle.gif)
</Frame>

* 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

<Warning>
  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.
</Warning>

Scheduled timer events are clearly indicated within the process definition list of an application at Runtime, as illustrated in the following example:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)
</Frame>

<Card title="Scheduled processes" href="../../../projects/runtime/scheduled-processes/" icon="page" />

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    |

<Warning>
  A process definition version should have a single Timer Start Event per swmilane.
</Warning>

For comprehensive details on each timer event node in this section, please refer to the corresponding documentation:

<CardGroup>
  <Card title="Timer Start Event (interrupting)" href="./timer-start-event" />

  <Card title="Timer Intermediate Event" href="./timer-intermediate-event" />

  <Card title="Timer Boundary Events" href="./timer-boundary-event" />

  <Card title="Timer expressions" href="./timer-expressions" />
</CardGroup>


# Timer expressions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-expressions

Configure timer expressions using Cron syntax for scheduling or ISO 8601 format for durations and timeouts.

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.

<Info>
  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.
</Info>

<Warning>
  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.
</Warning>

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:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_process_settings.png)
</Frame>

### 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 |

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/timer_response_timeout.png)
</Frame>

* [**Actions**](../../actions/actions) - **Timer expression** - it can be used if a delay is required on that action

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/timer_action_edit.png)
</Frame>


# Timer Intermediate Event (interrupting)
Source: https://docs.flowx.ai/5.9/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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_intermediate_event.png#center)
</Frame>

## Configuring a timer intermediate event (interrupting)

| Field      | Validations | Accepted Values                  |
| ---------- | ----------- | -------------------------------- |
| Definition | Mandatory   | ISO 8601 formats (date/duration) |
|            |             | Process param                    |

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/intermediate_timer_eventz.png)
</Frame>

### 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)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_timer_date.png)
</Frame>

#### 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/5.9/docs/building-blocks/node/timer-events/timer-start-event

A Timer Start Event initiates a process instance based on a specified time or schedule.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_start_interrupting.png#center)
</Frame>

<Info>
  Please note that a process definition version can accommodate only one **Timer Start Event**.
</Info>

## Configuration

The Timer Start Event supports two timer types:

| Timer Type | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| Date       | Specifies an exact date and time for triggering the event (ISO 8601 format)           |
| Cycle      | Specifies a repeating interval using ISO 8601 repeating intervals or cron expressions |

<Info>
  The Start Timer Event supports either ISO 8601 formats or Spring cron expressions for defining timer values.
</Info>

<Check>
  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)
</Check>

## Timer type details

### Date

Specifies an exact date and time for triggering the event. You can use ISO 8601 date format for accurate date-time representation.

When configuring a Date timer, you can set:

* **Date**: Select a specific date (format: yyyy-mm-dd) using the date picker
* **Time**: Set the specific time when the timer should trigger

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_date.png)
</Frame>

### Cycle

Specifies a repeating interval for triggering the event. For the Cycle timer definition, you can use either:

#### ISO 8601 repeating intervals

For standardized time intervals (e.g., "R5/PT10M" for repeating 5 times with 10 minutes between each)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_cycle_iso_repeating.png)
</Frame>

<Tip>
  When configuring a Cycle timer (ISO 8601 repeating intervals) you can set:

  * **Repeat Every**: The interval between triggers (e.g., "2 hours")
  * **# of repeats**: How many times the timer should trigger (e.g., "3")
  * **Infinite**: Option to make the timer repeat indefinitely
  * **Start Time**: When the timer should begin (format: yyyy-mm-dd)
</Tip>

#### Cron expressions

For more complex scheduling patterns (e.g., "0 0 12 \* \* MON-FRI" for 12pm every weekday)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_cycle_cron.png)
</Frame>

## Activate/deactivate start timer events

All timers can be activated/deactivated in the Runtime section under "Scheduled Processes":

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/active_timer_events.png)
</Frame>

<Warning>
  If a project contains multiple versions with Start Timer Event nodes, a scheduler will be generated only for the ones included in the version set in the active policy.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-03-11%20at%2014.35.21.png)
  </Frame>
</Warning>

## Usage examples

### Date timer example: Employee Onboarding Reminder

In this scenario, the Timer Start Event triggers an employee onboarding process at a specific date and time.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_event_scenario.png)
</Frame>

* 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

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_date_scenario.png)
</Frame>

* 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/onboarding_notification.png)
</Frame>

* 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.

### General rules

* Schedulers are generated only for builds that are part of the active policy.
* If you change the active policy, processes with Timer Start Event nodes might appear or disappear from the scheduled processes list if they aren't part of the active build.
* You can view scheduled processes in the Runtime section under "Scheduled Processes".
* When a build in the active policy is updated with new Timer Start Event settings:
  * The scheduler is updated based on the new settings.
  * The scheduler state (active or suspended) remains the same as before.


# User task node
Source: https://docs.flowx.ai/5.9/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

<Frame>
  ![User Task Node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/user_task_node.png#center)
</Frame>

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**: When enabled, 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.
* [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node

<Info>
  When encountering a step with `canGoBack` switched to false, all steps found behind it will become unavailable.
</Info>

#### 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)

<Check>
  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. All events that start with a configured pattern are consumed by the Engine. For example, `KAFKA_TOPIC_PATTERN` is the topic name pattern where the Engine listens for incoming Kafka events.
</Check>

* **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

#### Data Search

* **Update data search**: Send updates to the Data Search service after this node, allowing you retrieve data from various process instances.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/update_ds_tn.png)
</Frame>

## Configuring the UI

The **FlowX.AI 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.AI Designer**.
2. Select a workspace.
3. Select a project.
4. Select a **process**.
5. Select a **user task** **node** then click the **brush** icon to open the **UI Designer**.

### Predefined components

UI can be defined using the available components provided by FlowX.AI, using the UI Designer available at node level.

Predefined components can be split in 3 categories:

<AccordionGroup>
  <Accordion title="Root components">
    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:

    <Card title="Root components" href="../ui-designer/ui-component-types/root-components/root-components" />
  </Accordion>

  <Accordion title="UI components">
    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:

    <Card title="Component types" href="../ui-designer/ui-designer#user-task-node-ui-components" />
  </Accordion>

  <Accordion title="Form elements">
    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.AI 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:

    <Card title="Form elements" href="../ui-designer/ui-component-types/form-elements" />
  </Accordion>
</AccordionGroup>

### 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:

<Card title="Custom" href="../ui-designer/ui-component-types/root-components/custom" />


# Data mappers
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/data-mappers

Visually map data transfers between components while maintaining full backward compatibility.

## Overview

Use Data Mappers to define how data flows between components. Add JavaScript transformations for complex scenarios.

### Key concepts

<CardGroup>
  <Card title="Source Components" icon="paper-plane">
    Send data to another component to trigger execution

    * Parent processes
    * Integration flows
    * Business rules
  </Card>

  <Card title="Destination Components" icon="bullseye">
    Receive input from a source component to execute

    * Subprocesses
    * Workflows
    * Business rules
  </Card>
</CardGroup>

### Parameters & variables

Configure parameters and variables on the **Data Model** tab at process level.

<Tabs>
  <Tab title="Input Parameters">
    **Input Parameters**: Define the structure your component expects to receive for successful execution.

    **Input Variables**: Send actual data from source to destination component for execution.

    <Frame>
      ![Input Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp1.png)
    </Frame>
  </Tab>

  <Tab title="Output Parameters">
    **Output Parameters**: Define the structure your component returns to the source component after execution.

    **Output Variables**: Return actual data from destination to source component after execution.

    <Frame>
      ![Output Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp2.png)
    </Frame>
  </Tab>
</Tabs>

#### Parameter types by origin

<AccordionGroup>
  <Accordion title="Predefined Parameters">
    Established before the mapping action (e.g., input of a subprocess or workflow). These typically belong to **destination components** with fixed requirements.
  </Accordion>

  <Accordion title="Flexible Parameters">
    Defined during the mapping process. Associated with **source components** that specify where destination component data comes from.
  </Accordion>
</AccordionGroup>

## Prerequisites

<Warning>
  Plan your Data Model carefully before implementing Data Mappers. Proper setup ensures success.
</Warning>

### Data Model hierarchy

Understand the data model hierarchy to implement Data Mappers effectively:

<CardGroup>
  <Card title="Project Data Model" icon="building">
    **Organization Level**: Define reusable data structures (e.g., "customer", "client type") that you can share across all processes and workflows within your project.
  </Card>

  <Card title="Library Data Model" icon="books">
    **Enterprise Level**: Create organization-wide standardized data types that you can reuse across multiple projects by including the library as a dependency.
  </Card>

  <Card title="Process Data Model" icon="sitemap">
    **Process Level**: Define process-specific data structures while leveraging reusable components from project and library levels.
  </Card>
</CardGroup>

### Setup requirements

<Steps>
  <Step title="Define Project Data Model First">
    **Critical**: Define your project data model before creating processes. This enables:

    * Reusability across processes and workflows
    * Consistent data structures
    * Improved error prevention
    * Enhanced mapping experience
  </Step>

  <Step title="Include Example Values">
    Add meaningful example values to your data model attributes. This helps you:

    * Visualize attribute meaning and expected values
    * Test without separate mock data
    * Improve your configuration experience
  </Step>

  <Step title="Plan for Reusability">
    Design data structures that can be shared across multiple components:

    * Customer information structures
    * Common business entities
    * Standardized response formats
  </Step>
</Steps>

## Configuration

### Setting up process parameters

<Steps>
  <Step title="Configure Input Parameters">
    * Open the process you want to configure
    * Navigate to the **Data Model**
    * Select the **Input parameters** tab and click "Define parameters"

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp3.png)
    </Frame>

    <Info>
      Define parameters for each start node separately when you have multiple start nodes. Select nodes from the dropdown.

      <Frame>
        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp4.png)
      </Frame>
    </Info>

    * Define the schema based on the process's Data Model
    * Mark fields as optional if your component can function without those parameters. The optional flag indicates your component can operate without these parameters throughout its entire operation, not just during mapping.
    * **Note**: This centralizes input definition at the subprocess level, replacing the previous "data to send" configuration on the parent process

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp5.png)
    </Frame>
  </Step>

  <Step title="Configure Output Parameters">
    * Navigate to the **Data Model**
    * Select the **Output parameters** tab
    * Define the schema based on the process's Data Model

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/output_variables.png)
    </Frame>
  </Step>

  <Step title="Handle Multiple Start/End Nodes">
    * View all start or end nodes when your subprocess has multiple nodes
    * Use this for scenarios with exclusive gateways
    * Configure parameters independently for each node
  </Step>
</Steps>

<Info>
  **Process Start Prompts**: When you start a process with defined input parameters, the system generates input prompts based on required parameters to help with testing and validation.
</Info>

## Mapping scenarios

### Call activity mapping

#### Synchronous call activity

<CodeGroup>
  ```yaml Prerequisites theme={"system"}
  - Parent process with defined Data Model
  - Child process with input/output parameters on Data Model  
  - Project-level data model for reusable structures
  ```

  ```yaml Configuration Steps theme={"system"}
  1. Define call-activity type node
  2. Select subprocess to be called
  3. Choose Data Mapper implementation (default)
  4. Configure input/output mapping
  5. Test mapping with example values
  6. Save configuration
  ```
</CodeGroup>

<Steps>
  <Step title="Set Up Call Activity">
    * In a process, define a **call-activity** type node
    * Select the subprocess to be called
    * **Data Mapping is now the default option**
    * Toggle to "Switch to legacy mapping" if needed for backward compatibility

    <Info>
      The new Data Mapping functionality is now the default option, while legacy mapping remains accessible via a toggle for backward compatibility.

      <Frame>
        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/legacy.png)
      </Frame>
    </Info>

    <Info>
      Existing actions that were configured before this update automatically retain legacy mapping—there is no need for you to modify them unless you want to switch to the new Data Mapping.
    </Info>

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp7.png)
    </Frame>
  </Step>

  <Step title="Map Input Parameters">
    * View the subprocess's input parameters
    * Click the "key icon" next to the parameter

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp8.png)
    </Frame>

    * **Source Component**: Current process (parent)
    * **Destination Component**: Subprocess input parameters
    * **Mapping Options**:
      * **Individual Mapping**: Map each attribute individually using interpolation syntax: `${variableName}`
      * **Auto-populate Mapping**: Select the data model types from dropdown for automatic mapping of all attributes
      * **Quick Mapping**: If source and destination have the same data type, use dropdown for automatic mapping of all attributes

    <Tip>
      **Auto-populate Feature**: Instead of manually typing variable paths, select your data model types from the dropdown and the system will automatically populate all the mappings for you.
    </Tip>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp9.png)
    </Frame>

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/params_parent_process_dn.png)
    </Frame>

    * **Display Options**: You can view variables as schema or JSON format for better visualization
    * **Variable Format**: When mapping manually, use interpolation syntax `${variableName}` - this format differs from process keys
    * **Testing**: Click the "test" button to visualize the JSON payload using example values from your data model

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dm13.png)
    </Frame>
  </Step>

  <Step title="Map Output Parameters">
    * Select the **Output** tab
    * View subprocess's output parameters
    * Select attributes in parent process data model for storing output
    * Map subprocess output parameters (source) to parent process parameters (destination)

    <Frame>
      ![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_output.png)
    </Frame>

    **JavaScript Transformation**:

    To access JavaScript transformations, click the **function icon** next to the variable you want to transform.

    * **Use JavaScript functions** for data transformation and combination
    * **Syntax Requirements**: All computed values must use `return` statements
    * **Example**: `return ${userVerification.status} + " on " + ${userVerification.verificationDate}`

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/interpolation.png)
    </Frame>

    **Data Reference Syntax**:

    * **Dynamic values**: Use `${variableName}` syntax to reference dynamic values (same as used for variable mapping)
    * **Example**: `return ${approverName} + " approved on " + ${date}`

    **Testing and Persistence**:

    * **Testing**: Use test button to see transformed output with example values
    * **Value Persistence**: Previous values are saved until you click "confirmation" and "save"
    * **Error Handling**: JavaScript errors trigger when functions encounter issues (e.g., reading property from undefined object)

    **Type Handling**:

    * System sends configured data even with type mismatches (e.g., string to number)
    * Always validate your transformations before saving
  </Step>

  <Step title="Save Configuration">
    Save the mapping configuration for both input and output
  </Step>
</Steps>

#### Asynchronous call activity

<Note>
  For async nodes, output cannot be mapped as the parent process doesn't wait for completion.
</Note>

<Steps>
  <Step title="Set Up Async Call Activity">
    * Define **call-activity** node or **Start Subprocess** action on User Task
    * Select subprocess to be called
    * Check the **Run async** toggle
  </Step>

  <Step title="Map Input Only">
    * Choose Data Mapper implementation
    * Map input parameters from parent process (source) to subprocess (destination)
    * Save input mapping configuration
  </Step>
</Steps>

### Parallel multi-instance mapping

Use parallel multi-instance mapping when you need to start multiple subprocess instances simultaneously—one for each element in an array from the parent process.

<Info>
  **When to use**: This pattern is ideal for batch processing scenarios like processing multiple shipping orders, validating multiple documents, or handling multiple customer requests in parallel.
</Info>

#### Configuration options

When **Parallel Multi-instance** is enabled on a Call Activity node or Start Subprocess action, configure these options:

| Option                    | Description                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| **Input Array**           | The array from the parent process. Each element spawns a subprocess instance.            |
| **Output Array**          | The array in the parent process where subprocess results are collected.                  |
| **Correlation Attribute** | The attribute used to match subprocess results back to the correct parent array element. |

<Frame>
  ![Parallel multi-instance configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/call_activity_parallel_multi_instance.png)
</Frame>

#### Data mapping configuration

<Steps>
  <Step title="Enable Parallel Multi-Instance">
    * Open the **Call Activity** node or **Start Subprocess** action
    * Enable the **Parallel Multi-instance** toggle
  </Step>

  <Step title="Declare Arrays">
    * **Input Array**: Specify the parent process array containing the data to process (e.g., `ordersList`)
    * **Output Array**: Specify where to store the subprocess results (e.g., `processedOrdersList`)
  </Step>

  <Step title="Configure Input Mapping">
    * Click to open the mapping modal
    * Map array element attributes to subprocess input parameters
    * **Example**: Map `${item.orderId}` from parent array to `orderId` in subprocess

    <Frame>
      ![Parallel multi-instance mapping](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pmi_mapping.png)
    </Frame>
  </Step>

  <Step title="Configure Output Mapping">
    * Map subprocess output parameters back to the parent output array
    * Each subprocess instance's result is added to the output array
  </Step>

  <Step title="Set Correlation Attribute">
    * Define which attribute correlates subprocess results with parent data
    * This determines whether results **update existing** or **insert new** array elements
  </Step>
</Steps>

#### Correlation attribute behavior

When subprocess results return, the correlation attribute determines how data is handled:

<CardGroup>
  <Card title="Update Existing" icon="pen-to-square">
    When the correlation attribute value **matches** an element in the parent array, that element is updated with the subprocess result.
  </Card>

  <Card title="Insert New" icon="plus">
    When the correlation attribute value **doesn't match** any element in the parent array, the result is inserted as a new element.
  </Card>
</CardGroup>

#### Example: Processing shipping codes

**Scenario**: Process multiple shipping codes in parallel, determining package type for each.

<Steps>
  <Step title="Prepare Parent Process Data">
    Create an array of shipping codes using a business rule:

    ```java theme={"system"}
    import java.util.*;

    def mapValues(shippingCode) {
        return {
            "shippingCode": shippingCode
        }
    }

    shippingCodeList = [];
    shippingCodeList.add(mapValues("12456"));
    shippingCodeList.add(mapValues("146e3"));
    shippingCodeList.add(mapValues("24356"));
    shippingCodeList.add(mapValues("54356"));
    output.put("shippingCodeList", shippingCodeList);
    ```
  </Step>

  <Step title="Configure Call Activity">
    * Enable **Parallel Multi-instance**
    * Set **Input Array**: `shippingCodeList`
    * Set **Output Array**: `packageType`
    * Set **Correlation Attribute**: `shippingCode`
  </Step>

  <Step title="Map Input Parameters">
    * Map `${item.shippingCode}` → subprocess `shippingCode` input parameter
  </Step>

  <Step title="Subprocess Processing">
    In the subprocess, process each shipping code:

    ```java theme={"system"}
    import java.util.*;

    map = new HashMap();

    if (input.item.shippingCode.startsWith("1")) {
        map.package = "Fragile";
    } else {
        map.package = "Non-fragile";
    }

    map.shippingCode = input.item.shippingCode;
    output.put("result", map);
    ```
  </Step>

  <Step title="Result">
    Each subprocess returns its result, which is collected in the parent's output array:

    ```json theme={"system"}
    {
        "package": "Non-fragile",
        "shippingCode": "54356"
    }
    ```
  </Step>
</Steps>

<Warning>
  **Array changes reset mappings**: When you modify the input or output array configuration and save, any existing mappings are automatically deleted. Reconfigure your mappings after changing array definitions.
</Warning>

<Info>
  **Sync mode behavior**: When parallel subprocesses run in sync mode and the parent process token advances (due to another action), unfinished subprocesses are automatically dismissed.
</Info>

## Transforming arrays

When a parameter is an array, the data mapping panel maps it **wholesale**, you cannot map individual elements or sub-attributes from the UI. To filter, reshape, or compute over an array, switch to **function mode** by clicking the **f(x)** icon next to the parameter and use JavaScript on the resolved value.

<Warning>
  The `${...}` interpolation syntax resolves a **path** to its value, it does not evaluate JavaScript inside the braces. Method calls like `${application.documents.filter(...)}` will fail. Place the placeholder first, then chain methods on the result.
</Warning>

**Default mapping** (pass the array through, no transformation):

```js theme={"system"}
return ${application.documents};
```

**Filter an array**, keep only documents with `id` equal to 1:

```js theme={"system"}
return (${application.documents} || []).filter(doc => doc?.id === 1);
```

**Map to a new shape**, extract a single field from each element:

```js theme={"system"}
return (${application.documents} || []).map(doc => ({ documentId: doc.id }));
```

**Combine filter and map**:

```js theme={"system"}
return (${application.documents} || [])
  .filter(doc => doc?.status === "APPROVED")
  .map(doc => doc.id);
```

<Tip>
  Always default to `|| []` when chaining array methods on a placeholder. If the source path resolves to `undefined` (parameter not yet populated), `.filter()` and `.map()` would throw, the empty-array fallback keeps the mapping safe.
</Tip>

## Testing and validation

### Testing methodology

<Steps>
  <Step title="Use Example Values">
    * Use example values from your data model for testing
    * No need for separate mock data
    * Values automatically populate in test scenarios
    * **Auto-populate benefit**: Example values help visualize attribute meaning and expected data
  </Step>

  <Step title="Test Payload Generation">
    * Click "test" button to visualize JSON payload
    * See exactly what data will be sent to destination component
    * Verify transformations work as expected
    * **Display formats**: View results as schema or JSON for better understanding
  </Step>

  <Step title="Variable Mapping Validation">
    * Verify interpolation syntax `${variableName}` is correctly formatted
    * Test both manual mappings and auto-populated ones
    * Ensure data type compatibility between source and destination

    <Note>
      The interpolation format `${variableName}` used in Data Mappers differs from process key formats. Pay attention to this when manually entering variable paths.
    </Note>
  </Step>

  <Step title="Apply Previous Session Information">
    * Use information from previous sessions in testing
    * Validate real-world scenarios
    * Ensure data flows correctly end-to-end
  </Step>

  <Step title="Testing subprocess data">
    * When testing data coming from subprocesses, you need to check for the UUID instance of the subprocess and copy paste it in the instance field of the test data, as shown in the demo below:

    <video />
  </Step>
</Steps>

### JavaScript transformation testing

<AccordionGroup>
  <Accordion title="Syntax Requirements">
    * All computed values must include `return` statements
    * Use clear parameter notation (e.g., `userVerification.status`)
    * Functions must handle potential undefined values
  </Accordion>

  <Accordion title="Error Handling">
    * System sends data even with type mismatches
    * JavaScript errors trigger for undefined object property access
    * Test transformations thoroughly before deployment
  </Accordion>

  <Accordion title="Value Persistence">
    * Previous values are saved during configuration
    * Only lost upon clicking "confirmation" and "save"
    * Allows iterative testing and refinement
  </Accordion>
</AccordionGroup>

## Managing parameter changes

Different types of parameter changes require different handling - some propagate automatically while others need manual updates.

### Automatic propagation

These changes propagate automatically to input/output parameters and mappings:

<CardGroup>
  <Card title="Deleted Attributes" icon="trash">
    **Automatic removal**: When you delete an attribute from the data model, it disappears from input/output parameters and mappings
  </Card>

  <Card title="Renamed Attributes" icon="pen">
    **Automatic update**: When you rename an attribute in the data model, the change reflects in input/output parameters and mappings
  </Card>
</CardGroup>

### Manual intervention required

<CardGroup>
  <Card title="New Attributes" icon="plus">
    **Manual addition**: When you add new attributes to the data model, you must manually:

    1. Add them to input/output parameters
    2. Configure them in the data mapper
  </Card>
</CardGroup>

### Data Model propagation timing

Propagation speed varies by data model type:

<Info>
  When you don't alter data type structure (e.g., adding attributes or changing types), updates propagate as follows:

  * **Project data model**: Immediately
  * **Library data model**: After the dependency build is updated
</Info>

### Best practices for parameter changes

<Warning>
  Always test your mappings after any data model changes to ensure they function correctly.
</Warning>

## Use cases

Configure data mappers for these scenarios:

<AccordionGroup>
  <Accordion title="Start Subprocess Action">
    Mappings can be configured whether the subprocess is triggered from:

    * **Call Activity node**: Direct subprocess invocation within process flow
    * **User Task node**: Subprocess triggered by user interaction

    Both scenarios support full input and output parameter mapping capabilities.
  </Accordion>

  <Accordion title="Subprocess Execution Modes">
    Data mappers handle different subprocess execution patterns:

    * **Synchronous execution**: Parent process waits for completion, enabling both input and output mapping
    * **Asynchronous execution**: Parent process continues without waiting, supporting input mapping only
    * **Single instance**: One subprocess instance per trigger
    * **Parallel multi-instance**: Multiple subprocess instances started simultaneously from an array. See [Parallel multi-instance mapping](#parallel-multi-instance-mapping) for detailed configuration.
  </Accordion>

  <Accordion title="Reusable UI Template Integration">
    When integrating a pre-defined reusable UI template into a User Task node:

    * Map data from parent process to template input parameters
    * Configure template output to flow back to parent process
    * Enable consistent UI behavior across multiple processes
  </Accordion>
</AccordionGroup>

## Real-world examples

### Example 1: Monthly income collection

**Scenario**: A subprocess collects monthly income information from users and passes it back to the parent process.

<Steps>
  <Step title="Subprocess Design">
    * **UI Behavior**: Modal appears asking user to select currency and enter income amount
    * **Data Collection**: User enters monthly income value
    * **Requirement**: Pass collected data back to parent process
  </Step>

  <Step title="Data Model Configuration">
    **In the subprocess**:

    * Add `monthlyIncome` variable to the data model
    * Navigate to **Output Parameters** tab
    * Define `monthlyIncome` as an output parameter

    **In the parent process**:

    * Initially no input parameters needed (not sending data to subprocess)
    * Focus on receiving output data
  </Step>

  <Step title="Call Activity Mapping">
    * Open the **call activity** node in parent process
    * Navigate to **Input and Output Parameters** section
    * **Output mapping**: Connect subprocess output to parent process variable

    **Variable format**: Use `${monthlyIncome}` (interpolation syntax)

    <Tip>
      **Auto-mapping shortcut**: Select data model types from dropdown to automatically populate mappings instead of manual entry.
    </Tip>
  </Step>

  <Step title="Variable Renaming Example">
    * **Subprocess variable**: `monthlyIncome`
    * **Parent process variable**: `incomePerMonth` (renamed for clarity)
    * **Mapping**: `${monthlyIncome}` → `incomePerMonth`
    * **Result**: Two distinct data models successfully connected
  </Step>
</Steps>

### Example 2: Time-off approval with JavaScript transformation

**Scenario**: A colleague submits a time-off request, requiring approval with enhanced data transformation.

<Steps>
  <Step title="Request Flow Design">
    * **Input data**: Start/end dates, requester information
    * **UI Behavior**: Modal shows request details with approve/deny options
    * **Output requirement**: Return approval status + approver name
  </Step>

  <Step title="Input Parameter Mapping">
    * **Parent process sends**:
      * Approver name
      * Request details (start date, end date)
    * **Subprocess receives**: Input parameters for display

    **Configuration**: Parent process output parameters → Subprocess input parameters
  </Step>

  <Step title="JavaScript Transformation for Output">
    **Goal**: Combine approval decision with approver identity

    * Click the **function icon** next to the output variable
    * **Script example**:

    ```javascript theme={"system"}
    return ${approverName} + " approved on " + new Date().toISOString()
    ```

    **Dynamic value syntax**:

    * Use `${variableName}` to reference dynamic values: `${approverName}`

    <Warning>
      Always include `return` statements in JavaScript transformations.
    </Warning>
  </Step>

  <Step title="Testing Transformation">
    * Click **test** button to preview transformed output
    * Verify JavaScript logic with example data
    * **Result**: Enriched data flows back to parent process
  </Step>
</Steps>

<Info>
  **Key Takeaway**: Data Mappers enable not just data transfer, but also data enrichment and transformation through JavaScript, making them versatile tools for complex business workflows.
</Info>

## Best practices

<CardGroup>
  <Card title="Define Data Models Early" icon="clock">
    Establish project and library data models before creating processes for maximum reusability
  </Card>

  <Card title="Use Example Values" icon="lightbulb">
    Include meaningful example values in data models to improve testing and configuration experience
  </Card>

  <Card title="Plan for Reusability" icon="recycle">
    Design data structures that can be shared across multiple components and processes
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    Validate mappings and transformations with various data scenarios before deployment
  </Card>

  <Card title="Document Dependencies" icon="link">
    Note any dependencies between mapped parameters and transformation logic
  </Card>

  <Card title="Use Quick Mapping" icon="zap">
    Use quick mapping for components with identical data types to speed up configuration
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Do parameter changes propagate automatically?">
    **It depends on the change type**:

    * **Deleted attributes**: Automatically removed from mappings
    * **Renamed attributes**: Automatically updated in mappings
    * **New attributes**: You must manually add and configure them

    <Warning>
      Always test your mappings after making parameter changes to ensure they still function correctly.
    </Warning>
  </Accordion>

  <Accordion title="How do data mappers impact subprocess configuration?">
    When you start a subprocess using Data Mappers:

    * **No need to configure "Append Data to Parent Process" action** in the subprocess anymore
    * For **synchronous subprocesses**: Output automatically flows back to parent process
    * For **asynchronous subprocesses**: You can configure input mapping, and the subprocess can append data back to the parent process asynchronously
  </Accordion>

  <Accordion title="How do you set up process parameters with multiple end nodes?">
    You can define input and output parameters for each end node separately:

    * Navigate to **Data Model** → **Input/Output Parameters**
    * Select the specific node from the dropdown
    * Configure parameters independently for each end node

    <Info>
      Use this for processes with exclusive gateways where different entry points need different data structures.
    </Info>
  </Accordion>

  <Accordion title="What happens with currency variables in input mapping?">
    **Known limitation**: When you send a currency variable with amount and code as input, the system doesn't transmit the code because inputs don't collect the code from currency fields.

    **Solutions**:

    * Set the code as optional in the output parameters, OR
    * Gather the code separately using a segmented button or other input method

    <Warning>
      Handle this properly to avoid mapping errors.
    </Warning>
  </Accordion>
</AccordionGroup>

## Current limitations

Current limitations to be aware of:

<AccordionGroup>
  <Accordion title="Start Subprocess for collection item">
    * **Array to Object Mapping**: Cannot map array → object for scenarios when you edit or add an item in a collection *(estimated fix: 5.X Feature)*
  </Accordion>

  <Accordion title="Currency variable input mapping">
    * **Currency Code Transmission**: When mapping currency variables as input, only the amount is sent - the currency code is not transmitted
    * **Workaround Required**: Either make code optional in output parameters or collect currency code through separate input methods
  </Accordion>
</AccordionGroup>

## Related documentation

<CardGroup>
  <Card title="Call Activity Node" icon="arrow-right" href="../../building-blocks/node/call-subprocess-tasks/call-activity-node">
    Learn about call activity nodes and subprocess execution
  </Card>

  <Card title="Integration Designer" icon="puzzle-piece" href="../../platform-deep-dive/integrations/integration-designer">
    Discover workflow automation and external system integration
  </Card>

  <Card title="Data Model" icon="database" href="../../building-blocks/process/data-model">
    Understand process data structure and management
  </Card>
</CardGroup>


# Process data model
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/data-model

Manage key-value attributes inside process definitions, supporting strings, numbers, booleans, objects, arrays, and enums.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/data_model_new.png)
</Frame>

## Overview

The Data Model serves as the foundation for managing structured information throughout your process definitions. It provides a centralized approach to define, organize, and maintain the data attributes that drive your business processes and user interfaces.

### 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.36.00.png)
</Frame>

* **Currency Object Structure**:
  * Includes `amount` (numerical value) and `code` (ISO 4217 currency code, e.g., USD, EUR).
  * Example:
    ```json theme={"system"}
    {
      "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.

<Card title="Localization and internationalization" href="../ui-designer/localization-and-i18n" icon="page">
  Check this section for more details about l10n & i18n
</Card>

#### Date attribute

Dates are represented in ISO 8601 format and dynamically formatted based on locale and application settings.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.44.33.png)
</Frame>

* **Locale-Specific Date Formats**: FlowX.AI 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.

<Card title="Localization and internationalization" href="../ui-designer/localization-and-i18n" icon="page">
  Check this section for more details about l10n & i18n
</Card>

#### 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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.41.25.png)
</Frame>

* **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.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.42.16.png)
</Frame>

<Tip>
  These settings can be overriden at the application level or in the **UI Designer** for specific components.
</Tip>

* **Validation**:
  * Enforce range constraints (e.g., minimum and maximum values).
  * Input fields automatically apply formatting masks to prevent invalid data entry.

<Card title="Localization and internationalization" href="../ui-designer/localization-and-i18n" icon="page">
  Check this section for more details about l10n & i18n
</Card>

## Data model interface

When you open the Data Model, the left-side **Data Types** panel is minimized by default. Expand it to browse, search, and filter your data types. Selecting a data type or connector on the canvas highlights its location and scrolls to the parent data type.

<Frame>
  ![Data Model interface with settings side panel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/side_panel_overview.png)
</Frame>

***

## Creating and managing a data model

### Adding attributes to a data type

Each data type displays an **Add attribute** button for creating the first attribute. After the first attribute exists, the button appears only when you hover over the data type.

<Tip>
  **Key Naming Conventions**:

  * Keys in the data model are case-sensitive. This means 'customerName' and 'CustomerName' would be treated as two distinct attributes.
  * It's recommended to follow a consistent naming convention (such as camelCase) throughout your data model to avoid confusion.
  * Special characters and spaces in keys should be avoided.
</Tip>

When you add a new data type, a confirmation toast notifies you that it was successfully created.

### Attribute settings side panel

Selecting an attribute opens a **settings side panel** on the right with all configuration options for that attribute:

* **Type** — attribute type (string, number, boolean, object, array, enum, date, currency)
* **Validations** — required fields, range validation, pattern matching, custom validation
* **Sensitive data** — flag to hide values from process details and browser console
* **Reporting** — designate attributes for use in the reporting plugin
* **Example values** — provide sample values used in data mapping operations

<Tip>
  Example values remain as text input. Type-specific validators will be added in a future iteration.
</Tip>

### Attribute path

Each attribute displays a **path button** next to its name. Click it to view the full key path (for example, `customer.address.street`) and copy it to your clipboard. This is useful when referencing keys in business rules, UI component bindings, or integration mappings.

<Frame>
  ![Attribute path with copy button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/side_panel_overview.png)
</Frame>

### Validation rules

You can define validation rules for your data model attributes to ensure data integrity throughout your processes:

* **Required Fields**: Mark attributes that must have values before a process can proceed
* **Range Validation**: Set minimum and maximum values for numeric attributes
* **Pattern Matching**: Define regular expression patterns for string validation
* **Custom Validation**: Implement custom validation logic using business rules

<Tip>
  Validation rules can be defined at the data model level and enforced throughout UI components, business rules, and integration points, ensuring consistent data quality.
</Tip>

***

## Data model reference

The "View References" feature allows you to see where specific attributes are used within the data model. This includes:

* **Process Keys**: Lists all process keys linked to an attribute.
* **UI Elements**: Displays references such as the element label, node name, and UI Element key.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-18%2010.18.08.gif)
</Frame>

***

## Sensitive data

Protect sensitive information by flagging specific keys in the data model. This ensures data is hidden from process details and browser console outputs. You can configure this directly from the [attribute settings side panel](#attribute-settings-side-panel).

<Frame>
  <video />
</Frame>

***

## Reporting

The **Use in Reporting** tag allows you to designate keys for use in the reporting plugin, enabling efficient tracking and analysis. You can configure this directly from the [attribute settings side panel](#attribute-settings-side-panel).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/dm_reporting.png)
</Frame>

<Card title="Reporting" href="../../platform-deep-dive/plugins/custom-plugins/reporting/reporting-overview">
  Learn more about how to use Data Model attributes in the Reporting plugin.
</Card>

## Integration with other platform features

The Data Model serves as the backbone for numerous platform features, enabling consistent data flow between different components of your FlowX.AI application.

### Integration with UI Designer

The Data Model directly integrates with the UI Designer, allowing you to:

* Bind UI components to data model attributes
* Create dynamic UI layouts based on data model values
* Implement validation and formatting rules consistently across interfaces

### Integration with workflows

When designing workflows in the Integration Designer, you can use the Data Model to:

* Pass data from processes to workflows using the Start Integration Workflow action
* Map data between your process and external systems
* Transform and validate data during integration flows

<Card title="Workflow integration" href="../../platform-deep-dive/integrations/integration-designer#workflow-integration" icon="link">
  Learn more about integrating Data Model with workflows
</Card>

### Decision model integration

Data model attributes can be used as inputs for business rules, enabling:

* Complex business rule implementation using structured data
* Consistent data handling across decision points

## Best practices

### Structuring your data model

* **Use hierarchical structures**: Organize related data in nested objects to improve maintainability
* **Consistent naming**: Adopt a consistent naming convention for all attributes
* **Documentation**: Add clear descriptions for complex attributes to improve team understanding
* **Modularization**: Group related attributes into logical objects rather than using flat structures

### Version control and migration

When evolving your data model across versions:

* **Backwards compatibility**: Ensure changes don't break existing processes
* **Migration strategy**: Plan for how existing process instances will handle schema changes
* **Documentation**: Maintain clear documentation of data model changes between versions

## Troubleshooting

### Common issues

* **Missing data**: Ensure all required attributes are defined in your data model before referencing them
* **Type mismatches**: Verify that attributes are assigned the correct data type
* **Validation errors**: Check validation rules when data appears to be rejected

### Debugging tips

* Use the data model reference feature to track attribute usage
* Examine process instance data to verify attribute values
* Review UI component bindings to ensure proper data mapping

## Summary

The Data Model enables structured data management across your FlowX.AI applications. By following best practices for design, validation, and integration, you can build reliable process applications with consistent data handling throughout all stages of your business processes.


# Process design principles
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/design-principles

Foundational principles for designing FlowX processes. Covers modal usage, subprocess lifecycle, navigation, and platform behaviors.

## How to read this page

Every rule on this page is labeled with a **tier badge** (what kind of rule it is) and a **platform badge** (where it applies).

### Tiers

<Badge icon="triangle-exclamation">Must</Badge> Breaks if ignored. Unsupported or code-enforced.

<Badge icon="lightbulb">Recommendation</Badge> Bad idea but works. No code guard, but you will regret it.

<Badge icon="mobile">Platform behavior</Badge> Factual platform difference. Not a ban. Something to design around.

<Badge icon="scale-balanced">Context-dependent</Badge> Depends on platform or scenario. Read carefully.

### Platforms

<Badge icon="desktop">Web</Badge> Applies to web only.

<Badge icon="mobile">Mobile</Badge> Applies to mobile (iOS, Android) only.

<Badge icon="globe">Both</Badge> Applies to both platforms.

***

## Guiding principles

These are the foundational principles that everything else on this page derives from. Keep them in mind as you design.

1. **Web is a single-page application.** It renders whatever is pushed to the DOM.
2. **Mobile maintains a navigation history.** Users can navigate back.
3. **The main process and its subprocesses share the same navigation.**
4. **Subprocesses started from User Task actions must be only optional and secondary flows**, meaning modals.
5. **Be very intentional about when user tasks stay in the main process vs. move to Call Activities.** Keep them in the main process when you want the user to be able to go back. Keep them in Call Activities when you don't want the user to be able to go back once the subprocess has finished.
6. **Modals must be displayed on top of existing content.** The main process must not start with a modal.
7. **Asynchronously started subprocesses cannot have user tasks.** Multiple sibling subprocesses cannot share the same navigation history at the same time. The current subprocess must finish before a new one begins.
8. **Subprocesses without UI must not contain subprocesses with UI.**
9. **On mobile, you can have navigation inside the same modal.** Use this when the screens refer to the same user task split across multiple screens. Avoid nesting modals.
10. **On web, only one modal can be displayed at a time.** Nesting modals replaces the previous modal, and you cannot return to it.

***

## Modal design

### Modals must overlay existing content

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** A modal is rendered on top of existing content. If the process starts with a modal, there is nothing underneath. The modal becomes the only visible surface, which breaks its interruption semantics. It is also not in the back stack (see [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile)), so dismissing it from a first-screen position has no defined return target. The user experience cannot begin with a modal.

**Do this instead.** Make the first screen a **Page**. Open the modal over that Page when an interruption is actually needed (confirmation, acknowledgment, short focused task).

***

### Chaining modals: depends on platform and on whether subprocesses are involved

<Badge icon="scale-balanced">Context-dependent</Badge> <Badge icon="globe">Both</Badge>

The "don't chain modals" rule is not absolute. It depends on where you are and what's in the chain.

**Why.**

* **Web:** opening a second modal replaces the first modal in the DOM. You cannot return to the first modal. If that loss of back-navigation is acceptable for your scenario, it's a valid design. If not, don't chain.
* **Mobile:** two "modals" can be the same modal with internal navigation between them. This is allowed when the screens represent steps of the same user task. Do **not** nest separate modals on top of each other.

**Do this instead.**

* **Same-task multi-step on mobile:** use internal modal navigation, not a second modal.

***

### Do not use modals as loaders

<Badge icon="lightbulb">Recommendation</Badge> <Badge icon="globe">Both</Badge>

**Why.** A modal is an interruption that requires the user to act. A loading state isn't. The user can't interact with "wait." Using a modal as a loader blocks the user unnecessarily and misuses the modal's interruption semantics.

**Do this instead.** Use the **Show loader** option on event handlers for action-scoped loaders, or replace the default loader UI with the renderer SDK's custom loader API.

**Custom loader APIs in the SDKs.** Each renderer SDK exposes a custom loader API so the container app can replace the default loader per scenario (start process, save data, resume, etc.). Use those instead of a modal:

* [React renderer: Custom loader](../../../sdks/react-renderer#custom-loader)
* [Angular renderer: Custom loader](../../../sdks/angular-renderer#custom-loader)
* [Android renderer: Custom loaders](../../../sdks/android-renderer#custom-loaders)
* [iOS renderer: Custom loader](../../../sdks/ios-renderer#fxdatasource)

***

### No modal over modal

<Badge icon="scale-balanced">Context-dependent</Badge> <Badge icon="globe">Both</Badge>

**Why.**

* **Web:** only one modal can be displayed at a time. Nesting modals replaces the previous modal, and you cannot return to it (Guiding principle 10).
* **Mobile:** the OS automatically pops the current modal when the flow advances to the next screen (see [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile)). This is why two modals cannot be stacked on mobile at all. The recommended way to have navigation between modal-rendered screens is a single Modal navigation area with multiple User Tasks inside; mobile renders each User Task as a linked screen within the same modal.

**If you do nest modals, the choice must be intentional and the consequences understood.** On web, the previous modal is gone for good. On mobile, the OS auto-pops the first as soon as the second is pushed. Don't reach for nested modals as a shortcut.

**Do this instead.** On mobile, use internal modal navigation for same-task multi-step flows (one Modal nav area, two UTs). On web, use Pages or Stepper steps when you need to return to a previous screen.

***

### No two modals simultaneously

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** Only one modal can be displayed at a time (Guiding principle 10). The renderer does not reliably handle concurrent modals.

**Do this instead.** Resolve the current modal before opening another.

***

### Modals are not navigation containers

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** A modal must overlay existing content (Guiding principle 6). It is not a container for pages, steppers, tabs, or other navigation structures. Nesting navigation areas inside a modal breaks the Designer's render and dismiss logic.

**Do this instead.** Keep the modal as a leaf in the navigation tree. Put pages, steppers, and tab bars at the root of their respective zones, not inside a modal. See [Navigation best practices: What "child navigation areas" means](./navigation-best-practices#what-child-navigation-areas-means) for correct vs incorrect nav trees.

***

### Max modal depth is 1

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** Direct consequence of Guiding principles 9 and 10, and of how the OS back stack treats modals on mobile (see [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile)). On web, a second modal replaces the first. On mobile, the OS auto-pops the first modal the moment the second would be pushed, so two modals never coexist. The only scenario that produces a nominal depth greater than 1 is nested Call Activities, where each activity contains its own modal; this is a hierarchy artifact, not modal stacking, and is not a reason to plan around depth greater than 1.

**Enforcement.** This rule is enforced by design, not by a runtime guard. The Designer will accept configurations with deeper modal nesting, and the template config will load, but the rendering behavior in those cases is unsupported. Don't rely on the platform to catch a depth violation.

**Do this instead.** Design to a single modal depth. If you need a multi-step flow on mobile inside a modal, use internal modal navigation. If you need multiple distinct screens, use a Stepper or Pages.

***

### No cyclic modal paths

<Badge icon="lightbulb">Recommendation</Badge> <Badge icon="globe">Both</Badge>

**Why.** There is no code-level cycle detection for modal paths. A process loop that returns to a modal already in the current navigation path can confuse the user's navigation history and mental model.

**Do this instead.** Resolve the modal before looping. If the modal is part of the main sequential flow, replace it with a Step.

***

### Modals are dismissed only by user interaction

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** Modal lifecycle should be user-driven. A modal is an interruption; ending the interruption is the user's signal that they are ready to continue. Backend-driven auto-dismiss (timers, SSE events that the user didn't initiate, flow progression the user isn't aware of) breaks that contract.

**User-initiated chains are fine.** A dismiss that follows a user action is compliant, even when the close is delayed. Example: in UI Flows, a user clicks a button configured with Start Workflow and **Dismiss on completion**. The modal closes once the workflow finishes, but the dismiss is still a direct consequence of the user's click. That is not auto-dismiss.

**What to avoid.** Timer-based dismiss. Backend events that arrive independent of user action. Automatic close on flow progression without user acknowledgment.

**Do this instead.** Close modals via user triggers: confirm button, cancel button, close icon, backdrop click, or a user-initiated action whose completion dismisses the modal.

***

### Don't chain a modal user task to a Call Activity

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** Invoking a Call Activity from inside a modal user task dismisses the modal. There is no restoration path: the modal is not brought back when the Call Activity finishes, and the user loses the interruption context.

**Do this instead.** Resolve the modal first, then advance to the Call Activity from the Page or Step underneath. Don't put the Call Activity trigger inside the modal itself.

***

## Subprocess design

### A child subprocess does not dismiss its parent

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** The engine guarantees parent isolation. When a Call Activity or Embedded subprocess finishes, it signals the parent to continue, but does not terminate the parent. Dismissal does not cascade upward.

**Do this instead.** Treat a child's completion as a signal that resolves only the child. To propagate results up to the parent, use **Append Params to Parent Process** (to write into the parent's data model) or **Send data to user interface** with target **Parent process** (to push data into the parent's UI in real time).

***

### Call Activity subprocesses with Pages or Steppers appear in mobile back-nav

<Badge icon="mobile">Platform behavior</Badge> <Badge icon="mobile">Mobile</Badge>

**Why.** Mobile maintains a navigation history. When a Call Activity subprocess renders a **Page** or **Stepper**, those screens land in the shared back stack and the user can tap back into them while the subprocess is running. Modals, by contrast, are auto-popped on forward navigation and never appear in back-nav.

**What happens when the subprocess finishes.** The user is returned to the last screen of the parent process. The subprocess's screens are cleared from the back stack, so the user cannot return to them. See [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile) for the full mental model.

**Design for it.** Back-navigation targets should land on meaningful states, not orphaned or mid-step screens. Ask: "if the user taps back from the next screen, what makes sense to show them?"

**Context rule for modals after a Call Activity.** If a modal appears immediately after a Call Activity finishes, its context belongs to that Call Activity, not to the parent process. The user has not seen the parent's last screen for many screens; a modal referencing that parent context will feel disconnected. Either keep the modal inside the Call Activity, or make sure its content references what the user just completed.

***

### Avoid nesting a UI subprocess under a headless one

<Badge icon="lightbulb">Recommendation</Badge> <Badge icon="globe">Both</Badge>

**Why.** Subprocesses without UI should not contain subprocesses with UI (Guiding principle 8). When the immediate parent has no screens, the UI subprocess has no natural parent context, and the hierarchy becomes harder to read, maintain, and debug.

**Do this instead.** If a subprocess needs UI, its immediate parent should also have UI. Restructure so the UI subprocess is a sibling of the headless one, or promote the parent to have UI.

***

### UI subprocesses must start synchronously

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** Asynchronously started subprocesses cannot have user tasks (Guiding principle 7). An async UI subprocess races with the parent's token advance, and the UI gets dismissed before the user can complete it.

**Do this instead.** Use sync mode for any subprocess that contains user tasks. Reserve async mode for headless subprocesses (service tasks, integrations, notifications).

***

### Starting a subprocess from a User Task action

<Badge icon="triangle-exclamation">Must</Badge> <Badge icon="globe">Both</Badge>

**Why.** Subprocesses started from User Task actions must be only optional and secondary flows, meaning modals (Guiding principle 4). Mandatory UT actions that launch subprocesses block the flow if the subprocess cannot start.

**Do this instead.** Use modal-only navigation for the entry point, and keep the starting action **optional**. If the journey is mandatory, move it into a Call Activity on the main process, not behind a UT action.

***

## Related resources

<CardGroup>
  <Card title="Navigation best practices" icon="signs-post" href="./navigation-best-practices">
    Practical guide for choosing between Pages, Modals, Steppers, Tab Bars, and Zones.
  </Card>

  <Card title="Subprocess management" icon="diagram-project" href="./subprocess">
    Configuring, starting, and executing subprocesses, including mobile navigation behavior.
  </Card>

  <Card title="Navigation areas" icon="object-group" href="./navigation-areas">
    Reference for all navigation area types and platform-specific capabilities.
  </Card>
</CardGroup>


# Navigation areas
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/navigation-areas

Navigation areas play a pivotal role in user interface design. They enhance the user experience by providing a structured, organized, and efficient way for users to interact with and explore various features and solutions.

<CardGroup>
  <Card title="Stepper" href="#stepper">
    Sequential workflow navigation with progress tracking. Maximum 2 levels supported.
  </Card>

  <Card title="Tab Bar" href="#tab-bar">
    Multi-section navigation. Must be root component on mobile platforms.
  </Card>

  <Card title="Page" href="#page">
    Full-screen content display with wizard or single-page form options.
  </Card>

  <Card title="Modal" href="#modal">
    Temporary overlay for focused tasks. Use sparingly on mobile.
  </Card>

  <Card title="Zone" href="#zone">
    Layout container with headers/footers. Web-only feature.
  </Card>

  <Card title="Parent Process Area" href="#parent-process-area">
    Subprocess hierarchy management and design organization.
  </Card>
</CardGroup>

<Info>
  This page covers navigation areas in **BPMN processes**, where user tasks are assigned to areas. [UI Flows](../ui-flows) use the same navigation area types (Page, Tab Bar, Zone, Modal) but configure them directly in the UI Flows Designer as UI assets, without user tasks.
</Info>

<Info>
  In the navigation panel, the navigation hierarchy should be displayed beneath platform tabs, which include options for both web and mobile platforms. The default tab selected upon opening should be the web platform.
</Info>

## User task requirements

<Warning>
  **Critical Configuration Requirements**: All user tasks in your process must be included within navigation areas structure. It is a **misconfiguration** to have user tasks that are not associated with the navigation areas hierarchy.

  **Key Requirements:**

  * Every user task must be assigned to a navigation area
  * User tasks cannot be left empty - they must contain UI elements
  * All user tasks must be organized within the proper navigation hierarchy

  Failing to follow these requirements will result in runtime errors and poor user experience.
</Warning>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/nav_ares.gif)
</Frame>

## Platform-specific capabilities

### Web platform capabilities

* **Zone**: Used for organizing parts of screen with headers and footers
* **Zone/Page**: Supports wizard navigation and single-page form layouts
* **Tab Bar**: Optional placement and full navigation hierarchy support
* **Stepper**: Maximum 2 levels supported
* **Modal**: Full functionality with flexible usage patterns
* **Parent Process Area**: Complete subprocess design support

### Mobile platform capabilities

* **Tab Bar**: Must be positioned as first root navigation to define the entire application navigation structure
* **Stepper**: Maximum 2 levels supported
* **Modal**: Limited usage recommended (see recommendations below)
* **Parent Process Area**: Basic subprocess design support
* **Zone**: Not supported
* **Page**: Basic functionality only
* **1 User Task = 1 screen**: Mobile renders each User Task as its own screen. A multi-UT flow means multiple screens, one per task

### Platform support matrix

| Navigation Area         | Web | Mobile | Platform-specific notes                                        |
| ----------------------- | --- | ------ | -------------------------------------------------------------- |
| **Zone**                | ✅   | ❌      | Web only - used for organizing parts of screen                 |
| **Tab Bar**             | ✅   | ✅      | Mobile: must be first root navigation for entire app structure |
| **Page**                | ✅   | ✅      | Web: wizard navigation/single-page form support                |
| **Stepper**             | ✅   | ✅      | Maximum 2 levels across all platforms                          |
| **Modal**               | ✅   | ✅      | Mobile: specific usage recommendations apply                   |
| **Parent Process Area** | ✅   | ✅      | Subprocess design and hierarchy management                     |

## Getting started

This section covers the essential tasks for working with navigation areas: creating, configuring, and managing them in FlowX.AI Designer.

### Creating navigation areas

To create a new navigation area, follow these steps:

<Steps>
  <Step title="Access FlowX.AI Designer">
    Open **FlowX.AI Designer** and either open an existing process definition or create a new one.
  </Step>

  <Step title="Open Navigation View">
    Toggle the navigation areas menu by clicking on **Navigation view**.
  </Step>

  <Step title="Create New Area">
    Select **Create New Area** to begin configuring your navigation structure.

    <Info>
      Navigation configurations made on one platform (for example, Web) are not automatically duplicated to the other platform by default. You must copy or recreate them.
    </Info>
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/creating_nav_areas.gif)
</Frame>

### Managing navigation areas

Once you've created a navigation area, you can manage it through the breadcrumbs menu, which provides these options:

<AccordionGroup>
  <Accordion title="Area settings">
    <Frame>
      <img />
    </Frame>

    Use **Area Settings** to configure the following properties:

    * **Name** - a name for the navigation area element that is visible in the **Navigation menu**

    <Info>
      This does not represent the label for your navigation area (for example, for a step element) that would be visible in the process at runtime. To set the label for your element, use the UI Designer to edit it.
      To do that, trigger the **Navigation View** menu, then navigate to your element and click on the breadcrumbs. Afterward, click "UI Designer."
    </Info>

    * **Alternative Flows** - There might be cases when you want to include or exclude process nodes based on some information that is available as a start condition.
  </Accordion>

  <Accordion title="UI Designer">
    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_designer_navigation_areas.gif)
    </Frame>

    Use UI Designer to configure the following:

    * **Settings**:
      * **Generic**: Properties available cross-platform (Web, Android and iOS), available for all platforms
      * **Platform-specific configuration and styling**: For components across Web, iOS, and Android.
  </Accordion>

  <Accordion title="Copy/Paste">
    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/copy_paste_areas.gif)
    </Frame>

    The "Copy Navigation Areas" feature allows you to replicate navigation hierarchies and elements between different platforms.

    <Warning>
      The Copy/Paste Navigation Areas feature facilitates the duplication of navigation configurations within the same process definition and environment. It does not support copying across different process definitions or environments.
    </Warning>
  </Accordion>

  <Accordion title="Delete an area">
    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/delete_area.gif)
    </Frame>

    To delete a navigation area:

    1. Access the **Navigation view** menu within the FlowX.AI Designer.
    2. Choose the intended navigation area, then click on the breadcrumbs menu located on the right.
    3. Select **Delete Area**.

    <Warning>
      **Important**: Deleting the navigation area will also remove any associated child areas. Additionally, any user tasks contained within will be unassigned and relocated to the User Tasks section within the **Navigation view**.

      **Action Required**: After deleting a navigation area, you must reassign any unassigned user tasks to proper navigation areas. Leaving user tasks unassigned is a misconfiguration that will cause runtime issues.
    </Warning>
  </Accordion>
</AccordionGroup>

## Navigation area types

Choose the right navigation area type based on your user interface needs and platform requirements.

### Quick reference

| Type               | Use Case             | Web Support | Mobile Support | Key Features                   |
| ------------------ | -------------------- | ----------- | -------------- | ------------------------------ |
| **Stepper**        | Sequential workflows | ✅           | ✅              | Progress tracking, 2-level max |
| **Tab Bar**        | Section switching    | ✅           | ✅ (root only)  | Parallel content access        |
| **Page**           | Full-screen content  | ✅           | ✅              | Wizard/single-page modes       |
| **Modal**          | Focused tasks        | ✅           | ✅              | Temporary overlays             |
| **Zone**           | Layout structure     | ✅           | ❌              | Headers/footers (web only)     |
| **Parent Process** | Subprocess design    | ✅           | ✅              | Hierarchy management           |

### Available navigation types

You can create the following types of navigation areas:

<Frame>
  <img />
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/navigation_types.gif)
</Frame>

### Stepper

Sequential workflow navigation that breaks down complex processes into logical, numbered steps.

<Frame>
  <img />
</Frame>

**Key Features:**

* Progress tracking with visual indicators
* Return to previously visited steps
* Maximum 2 levels of nesting supported

<Warning>
  **Stepper  Recommendation**: FlowX supports a maximum of **2 levels** of stepper navigation across all platforms. Design your processes with this limit in mind to avoid navigation complexity. If you need more levels, consider breaking complex flows into separate processes.

  <Tip>
    If you need more levels, consider breaking complex flows into separate processes.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/stepper_in_steps.gif)
    </Frame>
  </Tip>
</Warning>

You can also define a stepper in step structure with the possibility to track progress and also returning to a previously visited step (as you can see in the navigation areas in the example above).

#### Stepper in step example

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/stepper_in_steps.gif)
</Frame>

#### Steps

Steps are individual elements within a stepper, simplifying complex processes.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/steps_ui_t.png)
</Frame>

### Tab Bar

Multi-section navigation component that allows users to switch between different areas of content.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tabs_view.gif)
</Frame>

**Key Features:**

* Parallel zone support within user tasks
* Quick switching between sections
* Support for nested tab structures

<CardGroup>
  <Card title="Parallel Zones">
    The navigation Tab Bar offers specialized support for **parallel zones** within the same **user task**. This feature allows users to navigate effortlessly between different sections or functionalities.
  </Card>

  <Card title="Multiple Tabs">
    Access multiple tabs within the tab bar for quick switching between various views or tasks.
  </Card>
</CardGroup>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tab_bar_nav_area.png)
</Frame>

When setting up a tab bar zone in your BPMN diagram, ensure that you always initiate a parallel zone using **Parallel Gateway** nodes. This involves using one Parallel Gateway node to open the zone and another to close it, as demonstrated in the example above. This approach ensures clarity and consistency in your diagram structure, facilitating better understanding.

<Warning>
  **Mobile Requirements**: On mobile devices, tab bars must be positioned as the **root component** in navigation and remain consistently visible, prioritizing ease of navigation.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/root_navigation_tab.png)
</Warning>

<Info>
  **Parallel scenarios must be independent.** Each parallel branch under a Tab Bar (and each Tab's content) should be a self-contained scenario, behaving as if it were its own process with no parallel siblings. Data can propagate between branches via normal FlowX mechanisms. Navigation cross-jumps between branches are not supported by design: the SDKs instantiate each branch with its own navigation scope, but there is no runtime firewall preventing cross-branch state leakage. Treat parallel branches as independent scenarios. See [Process design principles](./design-principles) for the full set of rules.
</Info>

<Info>
  **What a Tab can contain on mobile.** Tabs can hold User Tasks and Modals. They cannot hold Pages, nested Tab Bars, or Zones. Keeping the hierarchy flat is intentional: the mobile renderer relies on the Tab Bar being the consistent root.
</Info>

#### Tabs

Tabs are clickable navigation elements within the Tab Bar that allow users to switch between different sections or functionalities within an application.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tabs_parallel.png)
</Frame>

Each tab could contain a user task or multiple user tasks that can be rendered in parallel.

<Info>
  You can also use [**Start embedded subprocess**](../node/call-subprocess-tasks/start-embedded-subprocess) nodes to render defined subprocesses as a tab. Check the [**Start embedded subprocess**](../node/call-subprocess-tasks/start-embedded-subprocess) for more details.
</Info>

#### Tab bars inside tabs

In addition to regular tab bars, you have the option to implement nested tab bars, allowing for the display of another set of tabs when accessing a specific tab.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/nested_tab_bars.png)
</Frame>

To achieve this configuration, you'll need to create an additional parallel zone inside the previously created one for the main tab bar. This section should encompass the child tabs of the primary tab bar in your diagram. Once these child tabs are defined, close the parallel zone accordingly.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sub_tabs.png)
</Frame>

### Page

Full-screen content display that can contain multiple user tasks in parallel or sequential presentation.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/page_smth.gif)
</Frame>

A page could contain multiple user tasks displayed either in parallel (single page application) or one by one (wizard style).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_overview.png)
</Frame>

#### Navigation type (only for Web)

You have the possibility to add step-by-step or wizard-style navigation within a page (applicable when a page contains more than one User Task). This means you can navigate through the app in a guided manner, accessing each step within the designated area and page.

<Frame>
  ![Page navigation type options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_navigation_type.png)
</Frame>

* **Single page form** (default): The Web Renderer displays all User Tasks within the same page (in parallel).

<Frame>
  ![Single page form layout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_single_page.png)
</Frame>

<Tip>
  For optimal navigation, we suggest utilizing cards to guide users through the content.

  <Info>
    To maintain a clean UI while displaying user tasks on a single page, use cards as the root UI elements and apply accordions to them. This allows you to collapse each card after it is validated by an action.
  </Info>

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/cards_single_page_coll.gif)
</Tip>

<Info>
  Child areas will be rendered on the same page.
</Info>

* **Wizard**: For the Wizard option, the Web Renderer will display one user task at a time, allowing navigation using custom Next and Back buttons.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_wizard.gif)

<Tip>
  Child areas will be presented sequentially. It's crucial to configure actions properly to ensure smooth user navigation.
</Tip>

### Modal

Temporary overlay that interrupts the main flow to present focused tasks or information.

<Frame>
  ![Modal Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal.gif)
</Frame>

Modals offer temporary control over user interaction within a process, typically appearing as pop-ups or overlays. They guide users through specific tasks before returning to the main functionality of the application or website.

To enable user interaction with a modal, you can configure it to be dismissable in two ways:

* Dismiss on backdrop click
* Display dismiss confirmation alert

Here's how to configure these options:

1. Navigate to your configured modal and access the UI Designer.

<Frame>
  ![Modal UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal_ui_designer.gif)
</Frame>

2. In the UI Designer navigation panel, select the **Settings** tab, then choose **Generic**.

3. Check the box labeled "dismissable." If you also want to display a dismiss confirmation alert, configure the:
   * Title
   * Message
   * Confirm button label
   * Cancel button label

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal_configuration.png)
</Frame>

By configuring these options, you can customize the behavior of your modals to enhance user experience and guide them effectively through tasks.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal_example.gif)
</Frame>

<Note>
  **Modal title or header.** The Modal navigation area itself has no built-in `title` property. The only title field available on a Modal is the **dismiss confirmation alert title** (shown when a user tries to close a dismissable modal). To display a title or header inside the modal content on any platform, including mobile, place a Text or Heading UI component as the first element of the modal's user task content.
</Note>

### Zone

Web-only container for organizing layout with headers, footers, and structured content areas.

A Zone serves as a container designed to govern UI navigation by grouping specific elements together. Its optimal application is in scenarios involving processes featuring both a header and footer.

#### Navigation type (only for Web)

You have the possibility to add step-by-step or wizard-style navigation within a specific zone (applicable when a zone contains more than one User Task). This means you can navigate through the app in a guided manner, accessing each step within the designated area and page.

* **Single page form** (default): The Web Renderer will display all User Tasks within the same zone.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/single_page_form.png)

<Tip>
  For optimal navigation, we suggest utilizing cards to guide users through the content.
</Tip>

<Info>
  Child areas will be rendered on the same page.
</Info>

* **Wizard**: For the Wizard option, the Web Renderer will display one user task at a time, allowing navigation using custom Next and Back buttons.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/wizard.gif)

<Tip>
  Child areas will be presented sequentially. It's crucial to configure actions properly to ensure smooth user navigation.
</Tip>

<Warning>
  Zones with headers and footers are exclusively accessible in web configurations. They are not supported as navigation areas for mobile development.
</Warning>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header_footer.png)
</Frame>

#### How to Create a Header/Footer Zone

To establish a header/footer zone, follow these steps:

1. Begin by opening a new parallel zone and ensure to close it where you want the header/footer zone to end.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header%3Afooter_parallel.gif)
</Frame>

2. Introduce two new user tasks nodes within your process, designated to function as the header, respectively as footer.
3. Connect the first parallel gateway node to both of them.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/connect_header_footer.png)
</Frame>

4. Now connect the header and footer user tasks to the closing Parallel Gateway.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/connect_with_closing.gif)
</Frame>

3. In the navigation areas menu, incorporate a new zone labeled "Header Zone" and a new zone "Footer Zone".
4. Position the header at the top of your navigation structure or at the top within your primary navigation element and the footer at the bottom.
5. Assign the user tasks to the "Header Zone" and to the "Footer Zone".

<Info>
  When working with containers directly within navigation zones, you have the flexibility to set the sticky/static property directly on your specific navigation zone using the UI Designer, without having to add specific user tasks. However, determining the best practice depends on the specific use case you're aiming to implement.
  For instance, if you're looking to incorporate footers containing actions or buttons such as "Cancel application" or "Continue," it's advisable to include user tasks, allowing you to configure node actions effectively.

  <Tip>
    On the other hand, if your goal is to integrate static headers and footers featuring branding assets and external URLs, it's simpler to directly add them to the navigation areas. In this scenario, you can effortlessly incorporate images or text with external URLs on your containers styling.
  </Tip>
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header_footer_blaa.png)
</Frame>

6. Proceed to customize the user tasks UI according to your preferences.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header_footer_custom.gif)
</Frame>

#### Styling options

To customize the appearance of headers and footers, you need to utilize containers as the root UI elements for **user tasks** or navigation areas.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_ui.png)
</Frame>

You have two styling options available for these containers:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_configuration.gif)
</Frame>

* **Static**: This style remains fixed and does not scroll along with the page content.
* **Sticky**: When the sticky property is enabled, the container maintains its position even during scrolling.
  * **Layout**: You have the option to specify minimum distances between the container and its parent element while scrolling. At runtime, sticky containers will keep their position on scroll relative to top/ bottom/ right/ left margin of the parent element

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Screenshot%202023-12-13%20at%2017.18.39.png)
</Frame>

<Info>
  In mobile configurations, the right and left properties for sticky layout are ignored by the mobile renderer.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_demo.gif)
</Frame>

### Parent Process Area

Specialized container for managing subprocess design within parent process hierarchies.

**Use Cases:**

* Subprocess organization
* Hierarchy validation
* Design restriction enforcement

## Warnings

If you do not assign a user task to a navigation area, the platform will display a warning indicating that there are user tasks not included in the navigation structure (applies to all platforms).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wrn.png)
</Frame>

## Best practices and recommendations

<Card title="Navigation best practices guide" icon="compass" href="./navigation-best-practices">
  Detailed guidance on choosing between pages and modals, valid nesting combinations, common scenarios (phone verification, confirmations, multi-step forms), and anti-patterns to avoid.
</Card>

### User task configuration requirements

<Warning>
  **Mandatory User Task Organization**: Every user task in your process definition must be properly organized within navigation areas:

  * **Complete coverage**: All user tasks must be assigned to navigation areas - unassigned user tasks indicate a misconfiguration
  * **Non-empty user tasks**: User tasks must contain UI elements and cannot be left empty
  * **Proper hierarchy**: Organize user tasks within the appropriate navigation area hierarchy based on your process flow

  These requirements are essential for proper process execution and user experience.
</Warning>

### Mobile platform recommendations

* **Modal usage**: FlowX strongly recommends the use of modals only when you need to temporarily interrupt the normal (root) flow of the app, to present a focused task or message to the user, requiring the user to interact with it before returning to the main flow.
* **Important**: If finishing a task in a modal leads to navigating to another screen, and not just dismissing the modal, then the modal should be a root navigation area.
* **Tab bar implementation**: On mobile, tab bars must be positioned as first root navigation to define the entire application navigation structure and remain consistently visible.

### Cross-platform guidelines

* **Stepper complexity**: Maximum 2 levels supported across all platforms. Break complex flows into separate processes if more levels are needed.
* **Design approach**: Start with mobile constraints first, then enhance for web. Keep navigation structures simple and flat with clear visual indicators.
* **Web-specific features**: Use zones with headers and footers for comprehensive layouts. Use wizard navigation for complex processes and take advantage of larger screen real estate.

## Advanced features

### Demo and learning resources

For more information, you can also check the following demo on our Academy website:

<Card title="FlowX.AI Navigation view" href="https://academy.flowx.ai/explore/flowxai-navigation-view" icon="school" />

### Alternative flows

There might be cases when you want to include or exclude process nodes based on some information that is available at start.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/alternative_flows.png)
</Frame>

<Tip>
  For example, in case of a bank onboarding process, you might want a few extra BPMN nodes in the process in case the person trying to onboard is a minor.
</Tip>

For these cases, we have added the possibility of defining **alternative flows**.

For each navigation area or node, you can choose to set if they are only available in certain cases. In the example below, we will create two alternative flows in which we will include two different steppers and one modal without being part of an alternative flow.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/adding_alternative_flows.gif)
</Frame>

When starting a process, you must mention for the which flow the process will be initiated using the "navigationFlow" parameter and the name of the alternative flow:

```json theme={"system"}
{"navigationFlow": "First Flow"}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/alternative_flows_ex.gif)
</Frame>

<Info>
  If a node is not assigned to an alternative flow, this means the node will be included in all possible flows.

  <Tip>
    A node could also be a part of multiple flow names.
  </Tip>
</Info>

<Tip>
  When configuring alternative flows in the main process, remember that they will also be applied in any embedded subprocesses with identical names.
</Tip>


# Navigation best practices
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/navigation-best-practices

Guidelines for choosing the right navigation patterns, understanding valid combinations, and avoiding common misconfigurations in FlowX process design.

## Choosing the right navigation pattern

Picking the correct navigation area type is one of the most impactful decisions in process design. A wrong choice leads to broken flows, inconsistent behavior across platforms, and poor user experience.

Use this guide to decide **when** to use each navigation type and **how** to combine them correctly.

***

## Before you start

The foundational principles and per-rule classification (tier, platform, why, alternative) live on a dedicated page. Read them first, then come back here for practical decisions on how to combine patterns.

<Card title="Process design principles" icon="compass" href="./design-principles">
  Guiding principles, modal rules, and subprocess rules with platform tags and examples.
</Card>

***

## Page vs modal: the core decision

The most common mistake is using a modal when a page is needed, or chaining modals together. Whether modal chaining is acceptable depends on the platform — see [Chaining modals](./design-principles#chaining-modals-depends-on-platform-and-on-whether-subprocesses-are-involved) for the full rule. Here is how to decide between page and modal:

<Tabs>
  <Tab title="Use a Page when...">
    * The user needs to **complete a full step** in a flow (data entry, review, confirmation)
    * The content is **part of the main journey** and not an interruption
    * The user might need to **navigate back** to this screen
    * The flow involves **multiple sequential tasks** (use Wizard navigation type)
    * The content is **complex or long** (forms, tables, document reviews)

    **Examples:** Personal data form, account setup steps, document upload, application review
  </Tab>

  <Tab title="Use a Modal when...">
    FlowX strongly recommends the use of modals only when you need to temporarily interrupt the normal (root) flow of the app, to present a focused task or message to the user, requiring the user to interact with it before returning to the main flow.

    * The user needs to handle a **brief, focused interruption** before returning to the main flow
    * The task is **self-contained** and resolves with a single action (confirm, dismiss, acknowledge)
    * You need to show a **confirmation dialog** ("Are you sure?")
    * You need to display **supplementary information** without losing context (terms & conditions, help text)

    **Examples:** Confirmation dialogs, terms acceptance, single-field verification-code input, informational pop-ups
  </Tab>
</Tabs>

### Quick decision flowchart

Ask yourself these questions in order:

<Steps>
  <Step title="Is it a temporary interruption?">
    If the user will **do one thing and return** to where they were, consider a **Modal**.

    If the user is **progressing to a new step** in the flow, use a **Page** (or Step in a Stepper).
  </Step>

  <Step title="Does it lead to another screen?">
    If finishing a task in a modal leads to navigating to another screen, and not just dismissing the modal, then the modal should be a root navigation area.

    <Warning>
      This is the most common mistake. If your modal opens another modal or navigates to a page after completion, it should not be nested inside another navigation area.
    </Warning>
  </Step>

  <Step title="Is the content complex?">
    If the screen has **multiple form fields, validation logic, or scrollable content**, use a **Page**.

    Modals work best for **simple, focused interactions** (1-3 fields maximum).
  </Step>

  <Step title="Does the user need to go back?">
    Modals have **no back navigation**. If users might need to return to this screen from a later step, it must be a **Page** within a Stepper or Wizard.
  </Step>
</Steps>

***

## Modal rules

For the full set of modal rules (tier, platform, why, and alternatives), see [Process design principles → Modal design](./design-principles#modal-design).

A modal should not contain child navigation areas. It can contain user tasks and trigger workflows (including via On Load events), but it is not a container for pages, steppers, or other navigation structures.

### What "child navigation areas" means

In the Designer's **Navigation view**, you build a tree of navigation areas. **Child navigation areas** are areas nested inside a parent. Here is what a correct vs incorrect navigation tree looks like:

<Tabs>
  <Tab title="Correct">
    <Frame>
      ![Correct navigation structure — modal as leaf under a step](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigation_best_practices_correct.png)
    </Frame>

    The modal sits under a Step as a **leaf** — it contains user tasks but no child navigation areas.

    ```
    📂 Zone 1
    └── 📋 Stepper 1
        ├── ─○ Step - "Personal Data"
        ├── ─○ Step - "Documents"
        └── ─○ Step - "Review"
            └── 🪟 Modal - "Confirm Submit"    ← leaf, no child areas
    ```

    The modal is triggered as a brief interruption (e.g., "Are you sure?") and dismissed to return to the step.
  </Tab>

  <Tab title="Incorrect">
    Here the modal is used as a **navigation container** with areas nested inside it. The Designer allows this, but it causes rendering and dismiss behavior issues.

    ```
    🪟 Modal - "Verification flow"
    └── 📂 Zone                                ❌ zone nested inside modal
        └── 📋 Stepper
            ├── ─○ Step - "Enter code"         ❌ flow steps inside modal
            └── ─○ Step - "Verify code"
    ```

    Another common mistake: using multiple separate Modal navigation areas as sequential flow steps:

    ```
    📄 Page - "Enter Phone"
    🪟 Modal - "Sending..."                    ❌ modal used as loader
    🪟 Modal - "Enter code"                    ❌ second separate modal in sequence
    📄 Page - "Confirmation"
    ```

    For multi-step interactions that must stay inside a modal on mobile, use **one** Modal navigation area with multiple User Tasks inside, not two separate Modal areas. See [Chaining modals](./design-principles#chaining-modals-depends-on-platform-and-on-whether-subprocesses-are-involved).
  </Tab>
</Tabs>

<Warning>
  **Rule of thumb:** A modal can contain user tasks, but never other navigation areas. Don't nest pages, steppers, tabs, or other modals inside it.
</Warning>

### How modals fit in the navigation flow

A modal should overlay the current screen as a **temporary interruption** and return to the same context when dismissed:

```
Main flow:  [Page A] → [Page B] → [Page C]
                          ↓ ↑
                        [Modal]     ← brief interruption, returns to Page B or advances to Page C
```

Do **not** chain separate modals as sequential steps in the navigation:

```
❌  [Page] → [Modal A] → [Modal B] → [Page]     ← two separate Modal navigation areas
❌  [Page] → [Modal] → [Page] → [Modal]         ← modals are not steps in a flow
```

What actually happens depends on the platform:

* **Web:** opening a second modal replaces the first in the DOM. You cannot return to the first modal. If that loss of back-navigation is acceptable, it is a valid (though discouraged) design.
* **Mobile:** the OS auto-pops the current modal on forward navigation, so two separate modals cannot coexist. **For multi-step interactions inside a modal**, put multiple User Tasks inside a **single Modal navigation area** — mobile renders each User Task as a linked screen within the same modal with a built-in back button. This is the recommended pattern, not a workaround.

See [Chaining modals](./design-principles#chaining-modals-depends-on-platform-and-on-whether-subprocesses-are-involved) and [Max modal depth is 1](./design-principles#max-modal-depth-is-1) for the canonical rules.

<Info>
  In **UI Flows**, modals are navigation areas that you navigate to using the **Navigate To** action. The modal adds a `modalId` to the URL, which supports deep linking and survives page refresh. Use the **Dismiss modal** option or browser back to close.
</Info>

***

## Valid navigation combinations

### Navigation area nesting reference

The table below shows what the Designer allows you to add as child areas, and what you should actually use.

| Parent area       | Designer allows                                         | Recommended use                                                                                                                                                   |
| ----------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Root** (blue +) | Stepper, Tab Bar, Page, Modal, Zone, Parent Process     | Web: start with Zone for header/footer layouts, or Page/Stepper for simpler flows. Mobile: Tab Bar must be root for multi-section apps; otherwise Page or Stepper |
| **Zone**          | Zone, Stepper, Tab Bar, User Tasks, Embedded Subprocess | Stepper for multi-step flows, Tab Bar for section-based layouts                                                                                                   |
| **Stepper**       | Step                                                    | Add one Step per stage in the flow                                                                                                                                |
| **Step**          | User Tasks, Embedded Subprocess                         | One User Task per Step on mobile (1 UT = 1 screen)                                                                                                                |
| **Tab Bar**       | Tab                                                     | One Tab per section                                                                                                                                               |
| **Tab**           | Zone, Modal, Tab Bar, User Tasks, Embedded Subprocess   | Zone or Tab Bar for complex tab content (web); on mobile, prefer User Tasks or Modal                                                                              |
| **Page**          | Modal, Zone, Tab Bar, User Tasks, Embedded Subprocess   | Modal for brief interruptions only                                                                                                                                |
| **Modal**         | Zone, Tab Bar, User Tasks, Embedded Subprocess          | **Don't nest navigation areas under modals** — treat as leaf                                                                                                      |

The Designer applies the same allowed-children rules across web and mobile for Process navigation. Platform differences appear at runtime in the mobile renderers.

<Warning>
  **Mobile-specific behavior to design around:**

  * **Tab Bar must be the root navigation area on mobile.** If it appears anywhere else, the renderer will not behave correctly.
  * **Zone is not rendered on mobile.** On web it gives header/footer layouts; on mobile it is treated as a Page. Plan for this.
  * **One User Task per Page, Step, Tab, or Modal on mobile.** Mobile renders 1 UT as 1 screen, so multiple UTs under the same area is a misconfiguration.
  * **Nested navigation areas inside a Modal** are unsupported on mobile (iOS does not render them; Android renders them but the user experience is unpredictable). Treat the modal as a leaf.
</Warning>

### Patterns that work

<CardGroup>
  <Card title="Zone with Stepper (web only)" icon="check">
    Zone (header/footer) containing a Stepper with Steps. Each Step holds user tasks with form content.

    **Use for:** multi-step flows with persistent header/footer on web. Not available on mobile, where Zone is not rendered (treated as a Page).
  </Card>

  <Card title="Stepper with confirmation Modal" icon="check">
    Stepper with Steps for each stage. One Step contains a Modal for a brief confirmation before submission.

    **Use for:** forms that need an "Are you sure?" prompt before submit.
  </Card>

  <Card title="Page with Wizard navigation (web only)" icon="check">
    Single Page area with Wizard navigation type. Displays user tasks one at a time with Next/Back buttons.

    **Use for:** sequential data entry without visible step indicators on web. Not available on mobile (Wizard navigation does not exist).
  </Card>

  <Card title="Tab Bar with Tabs" icon="check">
    Tab Bar at root level with Tabs for each section. Each Tab can contain its own content and actions.

    **Use for:** Multi-section apps where users switch between areas.
  </Card>
</CardGroup>

### Patterns that break

<CardGroup>
  <Card title="Modal chain (two separate modals)" icon="xmark">
    Two separate Modal navigation areas chained sequentially. On web the second replaces the first in the DOM; on mobile the OS auto-pops the first.

    **Fix on web:** use Stepper steps or Wizard pages. **Fix on mobile:** put multiple User Tasks inside a single Modal navigation area (internal modal navigation).
  </Card>

  <Card title="Modal as flow step" icon="xmark">
    Page → Modal → Page where the modal is a step in the journey, not an interruption.

    **Fix:** Replace the modal with a Page or Step.
  </Card>

  <Card title="Modal as loader" icon="xmark">
    Opening a modal to show a loading spinner while a backend operation completes.

    **Fix:** Use the loading state properties on UI components (loader overlays, skeleton screens).
  </Card>

  <Card title="Deep nesting" icon="xmark">
    Zone → Stepper → Stepper → Stepper (more than 2 levels of stepper nesting).

    **Fix:** Break the flow into separate processes or subprocesses.
  </Card>

  <Card title="Cyclic modal path" icon="xmark">
    A process cycle that loops back into a modal already in the current navigation path.

    **Fix:** Resolve the modal before re-entering the loop, or replace the modal with a Page or Step.
  </Card>

  <Card title="Close-modal → open-modal" icon="xmark">
    One event that both dismisses the current modal and opens another.

    **Fix:** Split into two user-triggered actions, or replace with a Page/Step transition.
  </Card>

  <Card title="Modal → Call Activity" icon="xmark">
    A modal user task that triggers a Call Activity. The modal is dismissed and not restored when the Call Activity completes.

    **Fix:** Resolve the modal first, then transition to the Call Activity from a Page or Step.
  </Card>

  <Card title="Auto-dismissed modal" icon="xmark">
    A modal that closes on a timer, backend event, or automatic flow progression rather than user interaction.

    **Fix:** Require an explicit user action (confirm, cancel, dismiss button, backdrop click) to close the modal.
  </Card>
</CardGroup>

***

## Common scenarios

### Phone verification with a sent code

<Tabs>
  <Tab title="Recommended">
    Use a **Stepper** or **Page with Wizard** navigation:

    1. **Step 1 (Page):** user enters phone number
    2. **Step 2 (Page):** user enters the verification code with a resend option
    3. **Step 3 (Page):** confirmation, next step in the flow

    Each step is a proper page with back navigation support and clear progress indication.
  </Tab>

  <Tab title="Avoid">
    ❌ Page (enter phone) → Modal (show "sending code" loader) → Modal (enter code) → Page (confirmation)

    This chains modals as flow steps and uses a modal as a loader. It will not work correctly.
  </Tab>
</Tabs>

### Confirmation before submission

<Tabs>
  <Tab title="Recommended">
    Use a **Modal** for the confirmation dialog:

    1. User completes the form on a **Page**
    2. User clicks **Submit**
    3. A **Modal** appears: "Are you sure you want to submit?"
    4. User confirms → modal dismisses → process continues

    The modal is a brief interruption with a single action.
  </Tab>

  <Tab title="Avoid">
    ❌ Navigating to a separate confirmation **Page** for a simple yes/no question wastes a navigation step.

    ❌ Using a modal that then opens *another* modal for success/error feedback.
  </Tab>
</Tabs>

### Terms and conditions

<Tabs>
  <Tab title="Recommended">
    Use a **dismissable Modal**:

    1. User reaches a step that requires accepting terms
    2. User clicks "View Terms" → a **Modal** opens with the full text
    3. User reads and dismisses the modal
    4. User checks the acceptance checkbox on the **Page** and continues

    Configure the modal as dismissable (backdrop click or close button).
  </Tab>

  <Tab title="Avoid">
    ❌ Making the terms page a full navigation step in the Stepper, forcing the user through it sequentially.

    ❌ Embedding long scrollable legal text directly in the form page.
  </Tab>
</Tabs>

### Multi-section dashboard

<Tabs>
  <Tab title="Recommended">
    Use a **Tab Bar** with **Pages** for each section:

    * Tab 1: Account overview (Page)
    * Tab 2: Transaction history (Page)
    * Tab 3: Settings (Page with Wizard if multi-step)

    On mobile, the Tab Bar must be the root navigation area.
  </Tab>

  <Tab title="Avoid">
    ❌ Using modals to show different sections.

    ❌ Nesting Tab Bars more than 2 levels deep.
  </Tab>
</Tabs>

***

## Navigation selection guide

| Scenario                                 | Navigation type             | Why                                                   |
| ---------------------------------------- | --------------------------- | ----------------------------------------------------- |
| Multi-step form with progress            | **Stepper**                 | Users see where they are and can go back              |
| Sequential tasks without step indicators | **Page (Wizard)**           | Guided flow with Next/Back, no visible steps          |
| All fields on one screen                 | **Page (Single page form)** | Parallel display, use cards to group sections         |
| Brief confirmation or acknowledgment     | **Modal**                   | Quick interruption, single action, dismiss and return |
| Supplementary info (help, terms)         | **Modal (dismissable)**     | Read-only content that doesn't affect the main flow   |
| Multi-section app                        | **Tab Bar**                 | Parallel access to different areas                    |
| Persistent header/footer (web)           | **Zone**                    | Layout container for branding and global actions      |

***

## Related resources

<CardGroup>
  <Card title="Navigation areas" icon="signs-post" href="./navigation-areas">
    Configuration reference for all navigation area types.
  </Card>

  <Card title="UI Designer best practices" icon="paintbrush" href="../ui-designer/best-practices">
    General best practices for building interfaces.
  </Card>
</CardGroup>


# Passing data between nodes
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/passing-data-between-nodes

How outputs from subprocesses, workflows, AI agents, and business rules land in process variables, and how downstream nodes read them.

## Overview

Inside a BPMN process, every node, including subprocess, integration workflow, AI agent, business rule, and user task, reads from and writes to a shared store of **process variables** (also called *process instance data* in code).

This page explains the mental model: where each node type's output lands, and how the next node, or a user task screen, reads it. For the configuration syntax of any specific mapping, follow the links to the dedicated pages.

<Info>
  If you are calling FlowX from an external app (React frontend, another backend service) and want to fetch a process result over HTTP, that is a different question. See [Consuming FlowX from external apps](../../platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Info>

***

## The mental model

A process variable is a key on the process instance data store. Every node configures:

* **Input mapping**: which existing process variables to send into the node, or how to compute them.
* **Output mapping or result key**: where the node's output is written back into the process variables.

After the node finishes, downstream nodes and any user task screens that follow can read the result by referencing that key.

```
       ┌──────────────────────────────────────────────────────────┐
       │              Process variables (shared store)             │
       └──────────────────────────────────────────────────────────┘
              ▲                ▲                ▲              ▲
              │ output         │ output         │ output       │ read
              │                │                │              │
        ┌─────┴─────┐    ┌─────┴─────┐    ┌─────┴─────┐  ┌─────┴─────┐
        │ Subprocess│    │ Workflow  │    │ AI agent  │  │ User task │
        └───────────┘    └───────────┘    └───────────┘  └───────────┘
```

***

## Choose the right pattern

| If you need to…                                                        | Use this node                                                | Where its output lands                                                                         | Reference                                                                          |
| ---------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Run a stateful, multi-step BPMN flow with its own user tasks           | Subprocess (call activity)                                   | Mapped into parent variables via Data Mapper                                                   | [Data mappers](./data-mappers)                                                     |
| Call an integration workflow (REST, DB, AI ops) and capture the result | Send Message Task with **Start Integration Workflow** action | Written to the configured **Result key**, then a **Receive Message Task** unblocks the process | [Start Integration Workflow](../actions/start-integration-workflow)                |
| Call an AI agent (extraction, decision, generation)                    | Service Task with the agent integration                      | Mapped back to process variables in the action's output mapping                                | [BPMN integration with agents](../../../ai-platform/using-agents/bpmn-integration) |
| Compute or transform values inline                                     | Business Rule action                                         | Writes to keys passed to `output.put(key, value)`                                              | [Business rule action](../actions/business-rule-action/business-rule-action)       |

***

## The Receive Message Task pattern (workflows)

This is the part most people miss the first time.

When a process triggers an integration workflow with **Start Integration Workflow**, the process must wait for the workflow to finish before reading its output. To wait, place a **Receive Message Task** after the Send Message Task that triggers the workflow.

<Steps>
  <Step title="Add a Send Message Task">
    Configure it with the **Start Integration Workflow** action. Set the **Result key**: this is the process-variable path where the workflow's output will be written.
  </Step>

  <Step title="Add a Receive Message Task immediately after">
    The process pauses on this node until the workflow completes. When it completes, the workflow's output lands at the result key.
  </Step>

  <Step title="Read the result downstream">
    Any node after the Receive Message Task, including gateway, business rule, and user task, can read the result key from process variables.
  </Step>
</Steps>

For the full configuration walkthrough, see [Start Integration Workflow → Receiving output](../actions/start-integration-workflow#receiving-output) and [Send/Receive Message Task nodes](../node/message-send-received-task-node).

<Note>
  **For AI agents:** the integration is typically wired on a Service Task, and the agent's response is mapped back to process variables in the action's output mapping. No separate Receive Message Task is required. See [BPMN integration with agents](../../../ai-platform/using-agents/bpmn-integration).
</Note>

***

## Reading process variables downstream

Once a value is in process variables, the way you reference it depends on where you are reading from:

* **In another node's input mapping** (Send Message Task action, agent input, etc.): use the placeholder syntax documented on that node's page. Example for workflow input mapping: `${processInstanceData.customer.id}` (see [Start Integration Workflow → Input mapping](../actions/start-integration-workflow#input-mapping)).
* **In a subprocess's Data Mapper**: use `${variableName}` against the subprocess's defined Input Parameters. The Data Mapper is the canonical interface for parent ↔ subprocess data flow (see [Data mappers](./data-mappers)).
* **In a business rule script**: read from `input` (the keys you mapped in) and write to `output` via `output.put("keyName", value)`. See [Business rule action](../actions/business-rule-action/business-rule-action).
* **In a gateway condition**: reference the same process variables to choose a path.
* **In a user task screen**: bind UI components to process data. The value flows automatically once the variable exists in process instance data.

<Warning>
  The placeholder prefix is **not** universal. Subprocess Data Mappers use `${variableName}`; integration node config (workflow input, KB lookups) uses `${processInstanceData.path}`. Always follow the syntax shown on the destination page.
</Warning>

***

## End-to-end example

A loan-onboarding process that uses an integration workflow to fetch a credit score, then an AI agent to extract data from an uploaded document, then a user task to confirm the final summary.

<Steps>
  <Step title="User uploads document on a user task">
    The file id lands on process variables, for example at `loan.documentId`.
  </Step>

  <Step title="Send Message Task triggers a credit-check integration workflow">
    Input mapping reads `loan.customerId`. Result key set to `creditCheck`.
  </Step>

  <Step title="Receive Message Task waits for the workflow">
    When the workflow completes, its response lands at `creditCheck` in process variables.
  </Step>

  <Step title="Service Task calls the document-extraction agent">
    Input mapping sends `loan.documentId`. Output mapping writes the extracted fields to `loan.extracted`.
  </Step>

  <Step title="Final user task displays the summary">
    UI components on the screen are bound to `creditCheck` and `loan.extracted`. They render automatically because both keys now exist in process variables.
  </Step>
</Steps>

***

## Common pitfalls

<AccordionGroup>
  <Accordion title="Reading a workflow result before the Receive Message Task" icon="hourglass-half">
    The result key only contains data after the Receive Message Task unblocks. A node placed between Send and Receive will see an empty value.
  </Accordion>

  <Accordion title="Result key collision" icon="circle-exclamation">
    Two integrations writing to the same result key will overwrite each other. Use distinct, descriptive paths (`creditCheck`, `addressVerification`) instead of generic ones (`result`, `data`).
  </Accordion>

  <Accordion title="Wrong placeholder prefix" icon="square-xmark">
    `${variableName}` works in subprocess Data Mappers; `${processInstanceData.path}` works in integration node config. Mixing them produces unresolved placeholders at runtime. Follow the syntax shown on each node's page.
  </Accordion>

  <Accordion title="Expecting a synchronous result back to an external HTTP caller" icon="globe">
    Starting a process via REST returns metadata (process instance UUID, state), not the process's business output. To surface results to an external app, use the SDK, a Service Task callback, or a Kafka event. See [Consuming FlowX from external apps](../../platform-deep-dive/integrations/consuming-flowx-from-external-apps).
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Data mappers" icon="diagram-project" href="./data-mappers">
    Parent ↔ subprocess parameter mapping
  </Card>

  <Card title="Start Integration Workflow" icon="play" href="../actions/start-integration-workflow">
    Workflow input/output and the Receive Message Task pattern
  </Card>

  <Card title="BPMN integration with agents" icon="robot" href="../../../ai-platform/using-agents/bpmn-integration">
    Calling AI agents from a process
  </Card>

  <Card title="Business rule action" icon="code" href="../actions/business-rule-action/business-rule-action">
    Inline scripts that read from `input` and write to `output`
  </Card>

  <Card title="Send/Receive Message Task" icon="envelope" href="../node/message-send-received-task-node">
    Node-level configuration of the wait pattern
  </Card>

  <Card title="Consuming FlowX from external apps" icon="arrow-up-right-from-square" href="../../platform-deep-dive/integrations/consuming-flowx-from-external-apps">
    External HTTP/SDK integration patterns
  </Card>
</CardGroup>


# Permission-based expressions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/permission-based-expressions

Control UI element visibility and interaction based on user roles, usernames, and process data for granular access control.

Control what users see and edit within the same process instance based on their roles, usernames, or process data. One process definition automatically adapts to different users, providing role-specific interfaces and access control.

## Overview

Permission-based expressions enable you to:

* **Customize UI per role**: Different roles see different UI elements within the same process
* **Enable read-only access**: Users view and navigate process instances without making changes
* **Support concurrent work**: Multiple users with different permissions work on the same instance
* **Adapt dynamically**: UI changes in real-time based on user permissions and process data

<Info>
  **Use case examples**: A loan application where applicants see only input fields, reviewers see approval buttons, and managers see all data but in read-only mode. One process definition serves all roles.
</Info>

## Prerequisites

Before configuring permission-based expressions:

<Check>
  * Process definition created with swimlanes configured
  * User roles defined in the platform
  * **Allow multiple executors** enabled at the swimlane level (in process Settings → Permissions tab)
  * Understanding of your access control requirements
</Check>

## Permission capabilities

### Partial editing

Tailor UI element access for specific users, roles, or usernames within the same swimlane:

* **Role-based control**: Different roles see different UI elements
* **Username-specific access**: Individual users get customized interfaces
* **Data-driven permissions**: Process data determines what users can access

### Read-only access

Enable users to view and navigate process instances without modification:

* Users can navigate through user tasks and view data
* All input fields and buttons are non-interactive
* Hide and disable conditions continue to apply
* Navigation between tasks remains available

<Warning>
  **Configuration required**: Enable "Allow Read-Only Process Configuration" in process General settings, then assign **View** permission to appropriate roles at the swimlane level.
</Warning>

### Multiple executors

Multiple users with different roles work concurrently on the same process instance within a swimlane:

* Different permission levels (Execute, Self-assign, View) assigned to different roles
* Each user sees their role-specific interface
* Changes are synchronized across all active users
* Essential for collaborative workflows with varied responsibilities

## How permissions work

Permission-based expressions combine three key elements to control UI behavior:

### 1. Swimlane role configuration

Configure base permissions at the swimlane level:

* Assign roles (Execute, Self-assign, View) to user groups
* Enable **Allow multiple executors** to activate permission-based expressions
* Set minimum access level for each role

### 2. UI element conditions

Apply conditions to individual UI components to control visibility and interaction:

**Hide condition**

* Completely removes the UI element from the interface
* Available for all component types
* Element doesn't occupy any space in the layout

**Disable condition**

* Shows the element but prevents user interaction
* Available for forms, form elements, and buttons
* Element appears grayed out or visually disabled

### 3. Condition precedence

<Info>
  When both hide and disable conditions exist on the same element, **disable takes precedence**. The element will be shown in a disabled state rather than hidden.
</Info>

## Configuring permission-based expressions

Follow these steps to set up permission-based UI control for your process:

<Steps>
  <Step title="Enable multiple executors">
    Navigate to **Process Settings → Permissions** tab and enable **Allow multiple executors** for your swimlane.

    <Frame>
      ![Allow Multiple Executors Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_multiple_executors.png)
    </Frame>

    <Info>
      Configure role permissions (Execute, Self-assign, View) for each role that will access this swimlane.
    </Info>
  </Step>

  <Step title="Open UI Designer">
    Navigate to the **UI Designer** tab and select the component you want to configure with permission-based visibility or interaction controls.
  </Step>

  <Step title="Access permissions configuration">
    In the component properties panel, expand the **Permissions** section.

    <Frame>
      ![Permission Configuration Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pemission_%20based_ui.png)
    </Frame>
  </Step>

  <Step title="Add condition">
    Click the **+** button next to your desired condition type:

    * **Hide Condition**: Available for all component types
    * **Disable Condition**: Available for forms, form elements, and buttons
  </Step>

  <Step title="Configure condition parameters">
    Define the permission logic using these parameters:

    **Type**: Who the condition applies to

    * **USERNAME**: Target specific usernames
    * **ROLE**: Target users with specific roles

    **Operator**: How to evaluate the condition

    * **IN**: Condition applies when user matches the value
    * **NOT\_IN**: Condition applies when user does NOT match the value

    **Value Type**: Where permission data comes from

    * **SWIMLANE\_OWNER**: Current swimlane owner (automatic, no value needed)
    * **PROCESS\_DATA**: Reference data stored in the process instance
    * **CONFIGURATION\_SWIMLANE\_ROLE**: Use roles configured at swimlane level

    **Value**: The actual permission data (depends on Value Type)

    * **PROCESS\_DATA**: Process data keypath (e.g., `${app.client.userList}`)
    * **CONFIGURATION\_SWIMLANE\_ROLE**: Array of role names (e.g., `["ROLE_1", "ROLE_2"]`)
    * **SWIMLANE\_OWNER**: Not applicable (determined automatically)

    <Tip>
      Use `CONFIGURATION_SWIMLANE_ROLE` for static role-based permissions. Use `PROCESS_DATA` for dynamic, context-dependent permissions determined during process execution.
    </Tip>
  </Step>

  <Step title="Save configuration">
    Click **Save** to apply your permission-based expression. Test the behavior by accessing the process with different user roles.
  </Step>
</Steps>

## Common expression patterns

Use these examples as templates for typical permission scenarios:

### Role-based access control

Hide or disable elements for specific roles configured at the swimlane level:

```javascript theme={"system"}
{
  "type": "ROLE",
  "operator": "IN",
  "valueType": "CONFIGURATION_SWIMLANE_ROLE",
  "value": ["ROLE_MANAGER", "ROLE_SUPERVISOR"]
}
```

**Use case**: Show approval buttons only to managers and supervisors.

### Dynamic username lists

Control access based on usernames stored in process data:

```javascript theme={"system"}
{
  "type": "USERNAME",
  "operator": "IN", 
  "valueType": "PROCESS_DATA",
  "value": ["${app.client.authorizedUsers}"]
}
```

**Use case**: Display sensitive data only to users listed in an authorized users array populated during process execution.

<Tip>
  When using `PROCESS_DATA`, ensure data is mapped to the keypath **before** users reach the user task. Arrays must contain username or role strings.
</Tip>

### Swimlane owner restrictions

Limit access to the current swimlane owner only:

```javascript theme={"system"}
{
  "type": "USERNAME",
  "operator": "IN",
  "valueType": "SWIMLANE_OWNER"
}
```

**Use case**: Allow only the task owner to edit specific fields, while other team members can view but not modify.

### Exclusion patterns

Hide elements from specific users or roles using `NOT_IN`:

```javascript theme={"system"}
{
  "type": "ROLE",
  "operator": "NOT_IN",
  "valueType": "CONFIGURATION_SWIMLANE_ROLE",
  "value": ["ROLE_EXTERNAL_USER", "ROLE_VIEWER"]
}
```

**Use case**: Hide internal notes or administrative actions from external users and read-only viewers.

## Advanced: Cross-swimlane references

### Limitation

`SWIMLANE_OWNER` references only the owner of the **current swimlane**. You cannot directly reference owners from other swimlanes in the same process.

### Workaround: Store owners in process data

To reference users from other swimlanes, explicitly store their information in process data during swimlane transitions:

<CodeGroup>
  ```javascript Store swimlane owners during process execution theme={"system"}
  // Map during swimlane transitions or process start
  {
    "swimlaneOwners": {
      "frontOffice": "john.doe@company.com",
      "backOffice": "jane.smith@company.com", 
      "supervisor": "manager@company.com"
    }
  }
  ```

  ```javascript Reference stored swimlane owner theme={"system"}
  // Use in permission expression on any swimlane
  {
    "type": "USERNAME",
    "operator": "IN",
    "valueType": "PROCESS_DATA", 
    "value": ["${app.swimlaneOwners.frontOffice}"]
  }
  ```
</CodeGroup>

<Warning>
  Cross-swimlane owner references require explicit data mapping. Design your process to capture user information during swimlane transitions or use business rules to populate owner data.
</Warning>

**Implementation approach**:

1. Add a Business Rule node at the start of each swimlane
2. Capture the current user's username
3. Store it in your process data structure (e.g., `swimlaneOwners.{swimlaneName}`)
4. Reference this stored data in permission expressions on other swimlanes

## Best practices

Follow these guidelines for effective permission-based expressions:

<Tip>
  **Design principles**:

  * **Start simple**: Begin with role-based permissions before adding complex data-driven logic
  * **Test thoroughly**: Validate permission behavior with all user roles before deployment
  * **Document your logic**: Add comments in your process explaining complex permission patterns
  * **Minimize conditions**: Too many conditions can make UI behavior unpredictable and hard to maintain
  * **Use consistent naming**: Follow a standard naming convention for roles and process data keys
  * **Plan for edge cases**: Consider what happens when process data is missing or null
  * **Performance consideration**: Complex permission expressions on many components can impact rendering performance
</Tip>

<Warning>
  **Common pitfalls to avoid**:

  * Don't create circular dependencies between hide and disable conditions
  * Don't forget to test with users who have no assigned roles
  * Don't rely on process data that might not be populated yet
  * Don't use permission expressions as a substitute for proper swimlane role configuration
</Warning>

## Related resources

<CardGroup>
  <Card title="Access roles configuration" href="/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes" icon="user-shield">
    Set up user roles and permissions at the platform level
  </Card>

  <Card title="Swimlanes" href="/5.9/docs/platform-deep-dive/user-roles-management/swimlanes" icon="layer-group">
    Learn about swimlane configuration and role assignment
  </Card>

  <Card title="UI Designer" href="/5.9/docs/building-blocks/ui-designer/ui-designer" icon="paintbrush">
    Design user interfaces with permission-aware components
  </Card>

  <Card title="Process definition" href="./process-definition" icon="diagram-project">
    Complete guide to process definition configuration
  </Card>
</CardGroup>


# Process Designer
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/process

The Process Designer workspace is tailored for creating and editing business processes, featuring a menu with all the essential elements needed to design a process.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_dsgnr.png)
</Frame>

The Process Designer provides a visual, BPMN 2.0-compliant environment where you can create, edit, and manage business process workflows. Whether you're building simple linear flows or complex branching processes with multiple decision points, the designer gives you the tools to model your business logic effectively.

## Process Designer interface

When you open a process definition, you'll see the following essential elements:

<AccordionGroup>
  <Accordion title="1. Process definition name">
    The name of your process definition appears at the top, providing a clear identifier for the workflow. Click on the name to access process-level settings including permissions, expiry time, platform configuration, and task management options.
  </Accordion>

  <Accordion title="2. Process Nodes">
    The left panel contains the node palette with all available BPMN elements you can drag and drop onto the canvas. Nodes are organized by category: events, tasks, gateways, and subprocesses.

    <Tip>
      Hover over any node in the palette to see a tooltip with its name and primary use case.
    </Tip>
  </Accordion>

  <Accordion title="3. Navigation Areas">
    The Navigation section allows you to configure how users navigate through your process on web and mobile platforms. You can create steppers, modals, and other navigation structures that organize user tasks.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/nav_areas.png)
    </Frame>

    <Card title="Navigation Areas" href="./navigation-areas" icon="compass" />
  </Accordion>

  <Accordion title="4. Autosave">
    Changes to your process are automatically saved as you work, eliminating the need to manually save. The autosave indicator shows when your last change was saved, ensuring your work is never lost.

    <Info>
      Autosave works on draft versions. To make changes permanent and available to other environments, you need to commit your project version.
    </Info>
  </Accordion>

  <Accordion title="5. Canvas">
    The main canvas area is where you design your process flow by adding nodes, connecting them with sequences, and organizing them into swimlanes. The canvas supports zoom, pan, and offers visual feedback for validation warnings.
  </Accordion>

  <Accordion title="6. Warnings">
    The warning indicator displays misconfigurations that could prevent your process from executing correctly. Warnings are platform-specific and help ensure your navigation structure and UI configuration align with your selected platforms (Web, Mobile, or Omnichannel).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wrn.png)
    </Frame>

    <Warning>
      Address all warnings before publishing your process to production to avoid runtime errors.
    </Warning>
  </Accordion>

  <Accordion title="7. Node details">
    When you select a node, the right panel displays its configuration options. Here you can set node properties, add actions, configure UI elements for user tasks, and define business rules.
  </Accordion>
</AccordionGroup>

We have designed FlowX.AI components to closely resemble their BPMN counterparts for ease of use.

<CardGroup>
  <Card title="BPMN nodes" href="../node/node" icon="diagram-project">
    Comprehensive guide to all available node types
  </Card>

  <Card title="BPMN 101" href="https://academy.flowx.ai/explore/bpmn-101" icon="graduation-cap">
    Learn BPMN fundamentals through FlowX Academy
  </Card>
</CardGroup>

## Working with the canvas

The Process Designer canvas provides several features to help you efficiently create and manage process flows:

### Canvas navigation

* **Zoom**: Use the mouse wheel or zoom controls to zoom in and out of your process
* **Pan**: Click and drag on empty canvas space to move around large processes

### Adding and connecting nodes

<Steps>
  <Step title="Add a node">
    Drag a node from the left palette onto the canvas, or click a node type to add it to the center of your current view.
  </Step>

  <Step title="Connect nodes">
    Click on a node to select it, then click the arrow icon that appears. Click on the target node to create a sequence flow connection.

    <Tip>
      You can also create connections by dragging from the arrow icon on the source node to the target node.
    </Tip>
  </Step>

  <Step title="Configure the node">
    Select the node and use the right panel to configure its properties, actions, and behavior.
  </Step>
</Steps>

### Organizing your process

**Swimlanes**: Organize nodes by roles or departments using swimlanes. This helps visualize which parts of the process are handled by which teams and enables role-based access control.

**Layout best practices**:

* Arrange your process flow from left to right for better readability
* Use vertical spacing to separate parallel branches
* Group related nodes close together
* Keep crossing sequence flows to a minimum
* Use subprocesses to encapsulate complex logic

<Card title="Swimlanes" href="./process-definition#swimlanes" icon="layer-group" />

## Validating your process

Before publishing a process, ensure it meets all requirements:

### Validation rules

The Process Designer automatically validates your process and displays warnings for:

* **Missing required nodes**: Processes must have at least one START and one END node
* **Disconnected nodes**: All nodes must be reachable through sequence flows
* **Missing configurations**: User tasks without assigned navigation areas or UI elements
* **Platform mismatches**: UI configurations that don't align with selected platforms (Web/Mobile/Omnichannel)
* **Permission issues**: Swimlanes without proper role assignments
* **Invalid expressions**: Business rules or conditions with syntax errors

<Info>
  Click on any warning to navigate directly to the problematic node or configuration.
</Info>

### Testing your process

Before deploying to production:

1. **Start a test instance**: Use the test function to start a process instance in your development environment
2. **Monitor execution**: Watch how tokens move through your process and verify all paths work correctly
3. **Check data flow**: Ensure data is properly captured and passed between nodes
4. **Test all branches**: Verify that gateways route correctly based on different conditions
5. **Validate integrations**: Confirm external system connections work as expected

<Card title="Starting a process" href="../../flowx-designer/managing-a-project-flow/starting-a-process" icon="play" />

### Common validation errors

<AccordionGroup>
  <Accordion title="Process definition not found">
    **Cause**: The process hasn't been set as published or doesn't exist in the target environment.

    **Solution**: Ensure your process is part of a committed project version and deployed to the environment.
  </Accordion>

  <Accordion title="Start node not properly configured">
    **Cause**: Missing or misconfigured START node.

    **Solution**: Add a START node and ensure it has proper permissions configured if multiple start nodes exist.
  </Accordion>

  <Accordion title="Multiple start nodes without conditions">
    **Cause**: Multiple START nodes defined without start conditions to differentiate them.

    **Solution**: Add start conditions to each START node or remove extra START nodes.
  </Accordion>

  <Accordion title="User task not assigned to navigation area">
    **Cause**: A user task node hasn't been assigned to any navigation area.

    **Solution**: Open the Navigation view and assign the user task to an appropriate navigation area.
  </Accordion>
</AccordionGroup>

## Collaboration and versioning

### Working with multiple users

Multiple team members can work on processes simultaneously:

* **Concurrent editing**: Multiple users can view and edit processes within the same draft version
* **Real-time updates**: Changes made by other users appear automatically when you refresh
* **Conflict prevention**: The system prevents conflicting changes through optimistic locking
* **Change tracking**: The audit log records who made what changes and when

<Warning>
  When working with multiple users on the same process, communicate about major structural changes to avoid conflicts.
</Warning>

### Version management

Processes are versioned as part of projects:

* **Draft versions**: Work-in-progress changes that can be edited
* **Committed versions**: Finalized snapshots that are immutable
* **Version comparison**: Compare different versions to see what changed
* **Audit trail**: Track all changes with timestamps and user information

<CardGroup>
  <Card title="Versioning" href="../../projects/managing-applications/versioning" icon="code-branch">
    Learn about project versioning
  </Card>

  <Card title="Audit log" href="./process-definition#audit-log" icon="clock-rotate-left">
    View change history
  </Card>
</CardGroup>

## Best practices

<Tip>
  **Follow these guidelines for maintainable, performant processes**:

  **Design principles**:

  * Start simple with START and END nodes, then add complexity incrementally
  * Use clear, descriptive names for nodes and actions that explain their purpose
  * Document complex business logic in node descriptions
  * Create subprocesses for reusable logic or to simplify complex flows
  * Limit process complexity - if a process has more than 20-30 nodes, consider breaking it into subprocesses

  **Performance optimization**:

  * Minimize the number of nodes in frequently executed paths
  * Use parallel gateways judiciously - each branch creates additional tokens
  * Avoid deeply nested subprocesses when possible
  * Consider using timer events instead of polling for external events

  **Naming conventions**:

  * Use a consistent format like `[Department]_[Function]_[Action]` for process names
  * Name nodes to describe what they do, not what they are (e.g., "Validate Customer Data" instead of "Task Node 1")
  * Use uppercase for process-level constants and lowercase with underscores for data keys

  **Testing strategy**:

  * Test all decision branches with different input data
  * Verify error handling paths work correctly
  * Test with realistic data volumes for collection iterations
  * Validate all integration points before deployment
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Process won't save">
    **Symptoms**: Changes aren't being saved or the autosave indicator shows an error.

    **Solutions**:

    * Check your network connection
    * Verify you have edit permissions for the project
    * Ensure the project is in draft status (committed versions can't be edited)
    * Try refreshing the page and re-applying your changes
    * Check if another user has locked the resource
  </Accordion>

  <Accordion title="Nodes can't be connected">
    **Symptoms**: Unable to create sequence flows between nodes.

    **Solutions**:

    * Verify you're connecting compatible node types (e.g., END nodes can't have outgoing sequences)
    * Check if a sequence already exists between the nodes
    * Ensure nodes are in the same process (not trying to connect across subprocess boundaries)
    * Try zooming in - connection points might be difficult to target at small zoom levels
  </Accordion>

  <Accordion title="Process instances fail to start">
    **Symptoms**: Runtime errors when trying to start process instances.

    **Solutions**:

    * Review and resolve all validation warnings
    * Verify the process is published and included in an active build
    * Check that users have appropriate permissions (execute role)
    * Ensure all required integrations are configured and accessible
    * Review the exceptions log for detailed error messages

    <Card title="Failed process start" href="../../projects/runtime/active-process/failed-process-start" icon="triangle-exclamation" />
  </Accordion>

  <Accordion title="UI elements not displaying">
    **Symptoms**: Configured UI components don't appear when running the process.

    **Solutions**:

    * Verify user tasks are assigned to navigation areas
    * Check that UI elements are configured for the correct platform (Web/Mobile)
    * Ensure actions are set to "Manual" if they should be triggered by user interaction
    * Validate that the process platform setting matches your deployment (Web Only, Mobile Only, or Omnichannel)
    * Check hide/disable expressions aren't preventing element display
  </Accordion>
</AccordionGroup>

<Card title="Process Instance Monitoring" href="../../projects/runtime/active-process/process-instance" icon="chart-line">
  Learn how to monitor and debug running process instances
</Card>

In the following sections, we will provide more details on how to use the Process Designer and its components.

## Process definition

The process is the core building block of the platform. Think of it as a representation of your business use case, for example making a request for a new credit card, placing an online food order, registering your new car or creating an online fundraiser supporting your cause.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_designer.png)
</Frame>

A process is a series of steps that need to be followed to get to the desired outcome: getting a new credit card, gathering online donations from friends or having your lunch brought to you. These steps involve a series of actions, whether automated or handled by a human, that allows you to complete your chosen business objective.

<Card title="Process definition" href="./process-definition" icon="link" />

## Process instance

Once the desired processes are defined in the platform, they are ready to be used. Each time a process needs to be used, for example, each time a customer wants to request a new credit card, a new instance of the specified process definition is started in the platform. Think of the process definition as a blueprint for a house, and of the process instance as each house of that type that is being built.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/view_instance.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_instance.png)
</Frame>

From this point on, the platform takes care of following the process flow, handling the necessary actions, storing and interpreting the resulting data.

<CardGroup>
  <Card title="Process Instance" href="../../projects/runtime/active-process/process-instance" icon="link" />

  <Card title="Exceptions" href="../../projects/runtime/active-process/failed-process-start" icon="link" />

  <Card title="Debug 101 course" icon="graduation-cap" href="https://academy.flowx.ai/explore/debug-your-process-0">
    Learn debugging patterns, process/token status, error types, and exception handling
  </Card>

  <Card title="From Zero to Build course" icon="graduation-cap" href="https://academy.flowx.ai/explore/5from-zero-build-onboarding-project">
    End-to-end project build course covering all major platform features
  </Card>
</CardGroup>


# Process definition
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/process-definition

The core of the platform is the process definition, which is the blueprint of the business process made up of nodes that are linked by sequences.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_definitions.png)
</Frame>

## What is a process definition?

A process definition is the blueprint for your business processes. It defines the complete workflow logic—including nodes, sequences, decision points, user interactions, and integrations—that makes up your business process.

<Info>
  A process definition is like an architectural blueprint. The definition specifies how to build the structure, while process instances are the actual buildings constructed from that blueprint.
</Info>

### Key characteristics of process definitions

<CardGroup>
  <Card title="Executable Blueprint" icon="diagram-project">
    Once defined and published, process definitions can be instantiated, executed, and monitored in real-time
  </Card>

  <Card title="Version Controlled" icon="code-branch">
    Processes are versioned as part of projects, enabling safe evolution and rollback capabilities
  </Card>

  <Card title="Multi-Platform Support" icon="display">
    Configure processes for Web Only, Mobile Only, or Omnichannel deployment
  </Card>

  <Card title="Role-Based Access" icon="shield-check">
    Control who can view, execute, and modify processes using swimlanes and permissions
  </Card>
</CardGroup>

### Understand definitions and instances

Process definitions and process instances serve different purposes:

| Aspect            | Process Definition             | Process Instance                            |
| ----------------- | ------------------------------ | ------------------------------------------- |
| **Nature**        | Blueprint/template             | Actual execution                            |
| **When created**  | Design time                    | Runtime                                     |
| **Quantity**      | One per process type           | Many per definition                         |
| **Changeability** | Can be versioned and updated   | Immutable once started                      |
| **Contains**      | Node configurations, rules, UI | Current state, runtime data, token position |

<CardGroup>
  <Card title="Process instance" href="../../projects/runtime/active-process/process-instance" icon="play">
    Learn about running process instances
  </Card>

  <Card title="Failed process start" href="../../projects/runtime/active-process/failed-process-start" icon="triangle-exclamation">
    Troubleshoot process execution errors
  </Card>
</CardGroup>

## Manage the process lifecycle

The process lifecycle consists of seven stages, from initial design through deployment and optimization:

<Steps>
  <Step title="Design">
    Create your process definition using the Process Designer, adding nodes, configuring actions, and building the UI.
  </Step>

  <Step title="Configure">
    Set process-level settings including permissions, platforms, expiry time, and integrations with Task Manager or reporting.
  </Step>

  <Step title="Validate">
    Address any configuration warnings and test the process with sample data to ensure it works as expected.
  </Step>

  <Step title="Commit">
    Save your changes as part of a committed project version, making them available for deployment.

    <Info>
      Committed versions are immutable. To make further changes, create a new draft version.
    </Info>
  </Step>

  <Step title="Build and Deploy">
    Include the process in a project build and deploy it to your target environments (development, staging, production).
  </Step>

  <Step title="Execute">
    Process instances are created from the definition when users or systems trigger the process.
  </Step>

  <Step title="Monitor and Optimize">
    Track process performance, identify bottlenecks, and iterate with new versions to improve efficiency.
  </Step>
</Steps>

<Card title="Creating a process definition" href="../../flowx-designer/managing-a-project-flow/creating-a-new-process-definition" icon="plus">
  Step-by-step guide to creating your first process
</Card>

## Work with core components

Process definitions consist of six integrated workspaces and tools that work together to create business applications:

<Frame>
  ![Process definition menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_def_opts.png)
</Frame>

### 1. Process Designer

The visual BPMN 2.0 workspace where you create and edit process logic using a drag-and-drop interface.

<Frame>
  ![Process Designer Canvas](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_dsgn.png)
</Frame>

**Key features**:

* **Node palette**: Access all BPMN node types (User Tasks, Service Tasks, Gateways, Events, etc.)
* **Swimlanes**: Organize process steps by role or department for access control
* **Canvas controls**: Zoom, pan, and navigate large process diagrams
* **Sequence flows**: Connect nodes to define the execution path
* **Visual feedback**: Real-time validation warnings and configuration status

<Card title="Process Designer" href="./process" icon="pen-ruler">
  Complete guide to the Process Designer workspace
</Card>

### 2. UI Designer

The visual workspace where you design user interfaces for process interactions without code.

<Frame>
  ![UI Designer Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_designer_proc_def.png)
</Frame>

**Key features**:

* **Component library**: Pre-built UI components (Forms, Inputs, Buttons, Tables, Cards, etc.)
* **Drag-and-drop design**: Build interfaces by dragging components onto the canvas
* **Live preview**: See how your UI will appear to users in real-time
* **Platform-specific design**: Configure separate UIs for Web, iOS, and Android
* **Data binding**: Connect UI elements directly to process data
* **Theme support**: Apply consistent styling across your application

<Card title="UI Designer" href="../ui-designer/ui-designer" icon="palette">
  Learn about UI component configuration
</Card>

### 3. Data Model

Define the structure and schema for all data that flows through your process.

<Frame>
  ![Data Model Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_dm.png)
</Frame>

**Key features**:

* **Type definitions**: Create reusable data structures with typed fields
* **Visual relationships**: See how data objects connect and reference each other
* **Input parameters**: Define what data the process expects to receive
* **Output parameters**: Specify what data the process returns
* **Example values**: Include sample data for testing and development
* **Validation rules**: Ensure data integrity with type checking

<Card title="Data Model" href="./data-model" icon="database">
  Comprehensive data modeling guide
</Card>

### 4. Settings

Configure process-level settings including naming, permissions, integrations, and platform options.

<Frame>
  ![Settings Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/settings_interface.png)
</Frame>

**Configuration tabs**:

* **Process Name**: Set the unique identifier with naming constraints
* **General**: Platform selection, reporting, task management, expiry time
* **Permissions**: Configure swimlane roles and access control
* **Task management**: Integration with Task Manager plugin
* **Data Search**: Define searchable and filterable process data keys

**Access settings**: Click the settings icon in the left sidebar or use the top navigation menu.

### 5. Start a process for testing

Click the **Start Process** button in the top-right corner to test your process directly from the designer.

**Capabilities**:

* Automatically generates input forms based on your defined input parameters
* Validates required data before the process starts
* Creates a test process instance in your current environment
* Helps you test and debug during development

<Tip>
  When you have input parameters defined, the Start Process function will automatically generate input fields for required data, making it easy to test your process with sample values.
</Tip>

<Card title="Starting a process" href="../../flowx-designer/managing-a-project-flow/starting-a-process" icon="play">
  Learn more about starting and testing processes
</Card>

### 6. Access additional operations

Click the contextual menu (three-dot icon ⋮ in the top-right corner) to access essential process operations:

<Frame>
  ![Contextual menu options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/proc_contextual.png)
</Frame>

<Info>
  **Two contextual menus for process management:**

  This menu is available when you're **inside** a process definition, actively editing it. There's also a separate contextual menu available from the **Processes list view** (before opening a process) that provides operations like Export, Duplicate, Copy to another project, and See used resources.
</Info>

<Card title="Managing processes from the list view" href="../../flowx-designer/managing-a-project-flow/creating-a-new-process-definition#managing-process-definitions" icon="list">
  Learn about the Processes list contextual menu for export, duplicate, and copy operations
</Card>

<AccordionGroup>
  <Accordion title="Clear Cache">
    Clear cached process definition data to force a refresh from the database.

    **When to use**:

    * After making significant changes that aren't reflecting in the UI
    * When experiencing unexpected behavior or outdated data display
    * To troubleshoot synchronization issues

    <Info>
      This only clears the cache for the current process definition in your browser session.
    </Info>
  </Accordion>

  <Accordion title="Audit Log">
    View comprehensive change history for the process definition.

    **Information tracked**:

    * Timestamp of each change
    * User who made the change
    * Application version
    * Subject and event type
    * Subject identifier
    * Status of the change

    **Features**:

    * Filterable entries for easy tracking
    * Complete audit trail for compliance
    * Version comparison capabilities

    <Card title="Audit documentation" href="../../platform-deep-dive/core-extensions/audit" icon="clock-rotate-left" />
  </Accordion>

  <Accordion title="View History">
    Access the version history of the process definition to see all changes over time.

    <Frame>
      ![View History](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/history2.png)
    </Frame>

    <Frame>
      ![View History](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/history1.png)
    </Frame>

    **Capabilities**:

    * Compare different versions side-by-side
    * See what changed between versions
    * Track evolution of the process definition
    * Identify when specific changes were introduced

    <Info>
      This shows the version history within the project versioning system, allowing you to see how the process evolved across committed versions.
    </Info>
  </Accordion>

  <Accordion title="Delete">
    Remove the process definition from the project.

    <Frame>
      ![Delete process definition](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/delete_process.png)
    </Frame>

    <Warning>
      **Use with caution**: Deleting a process definition is a significant action that should only be performed when:

      * The process is no longer needed
      * You've verified that no other processes reference this one as a subprocess
      * You have appropriate backup or version control
    </Warning>

    **Impact**:

    * The process definition is removed from the current wip version (you cannot delete a process definition that is part of a committed version)
    * References from other processes may break
    * Historical data of process instances is not affected
    * Can be recovered from previous committed versions if needed
  </Accordion>
</AccordionGroup>

## Define your data model

The data model defines the structure of all data in your process. It acts as the schema for process variables, letting you organize and manage data throughout the process lifecycle.

<Info>
  Access the data model directly from the process definition interface to add new key-value pairs without switching menus.
</Info>

### Why define a data model?

Defining your data model provides several benefits:

* **Type safety**: Prevent errors during process execution by defining data types
* **Auto-completion**: Get intelligent suggestions in UI Designer based on defined keys
* **Validation**: Ensure data consistency across nodes and actions
* **Documentation**: Use the data model as living documentation of your process data structure
* **Reusability**: Reference data structures across multiple nodes and actions
* **Testing**: Include example values to test without creating mock data

<Tip>
  **Best practice**: Define your data model structure at the project level before building processes. This enables reusability across processes and improves consistency.
</Tip>

For comprehensive information on working with the Data Model, including advanced features like input/output parameters and data mappers:

<Card title="Data model" href="./data-model" icon="scroll" />

### Configure input and output parameters

Define the data contract for your process by specifying what data it receives (inputs) and what data it returns (outputs). These parameters are essential for subprocesses, workflows, and process testing.

#### Access parameter configuration

To configure parameters, navigate to the **Data Model** tab.

**Input parameters**

Input parameters define the data structure your process expects when it starts or when called as a subprocess:

* Enable process start validation
* Generate automatic input prompts for testing
* Support Call Activity nodes and subprocess integration

**Output parameters**

Output parameters define the data structure your process returns after execution:

* Return data to parent processes
* Enable synchronous subprocess communication
* Replace manual "Append Data to Parent Process" actions

<Frame>
  ![Input parameters configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp5.png)
</Frame>

#### How to configure parameters

To configure input or output parameters:

1. Navigate to **Data Model** → **Input/Output Parameters**.
2. Click **Define parameters**.
3. Configure the schema:
   * Add the parameter name and data type.
   * Mark parameters as required or optional.
   * Add descriptions and example values.
4. If you have multiple start or end nodes, select the specific node from the dropdown.

<Warning>
  **Required parameters**: Missing required parameters will cause process start failures. Only mark parameters as optional if your process can truly function without them.
</Warning>

<Tip>
  **Best practice**: Define parameter schemas based on your project-level data model for consistency and reusability.
</Tip>

#### Key features

* **Automatic validation** of required parameters
* **Type checking** ensures data integrity
* **Change propagation**: Deleted/renamed attributes automatically update in mappings
* **Multiple nodes support**: Different parameters for different start/end points

<CardGroup>
  <Card title="Data mappers" href="./data-mappers" icon="arrow-right-arrow-left">
    Complete guide to mapping data between components
  </Card>

  <Card title="Call Activity node" href="../node/call-subprocess-tasks/call-activity-node" icon="diagram-subtask">
    Using parameters with subprocess calls
  </Card>
</CardGroup>

## Organize processes with swimlanes

Swimlanes provide a visual and functional way to organize process nodes by participants or roles. You can structure your process by dividing it into horizontal lanes, with each lane representing different actors, departments, or responsibility areas.

<Info>
  Swimlanes serve two purposes: they provide visual organization in the process designer and enforce role-based access control at runtime.
</Info>

### Benefits of using swimlanes

Use swimlanes to:

* **Improve visual clarity**: Show which team or role is responsible for each process step
* **Control access**: Restrict who can execute, view, or self-assign tasks in each lane
* **Ensure compliance**: Enforce separation of duties by distributing tasks across different roles
* **Optimize processes**: Identify bottlenecks by seeing which roles handle the most tasks

### Add swimlanes

To add swimlanes to your process definition:

<Steps>
  <Step title="Open the process">
    1. Access the **FlowX.AI Designer**
    2. Open an existing process definition or create a new one
  </Step>

  <Step title="Access swimlane menu">
    Identify the default swimlane and select it to display the contextual menu.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/add_swimlane.png)
    </Frame>

    <Tip>
      With the contextual menu, you can easily perform various actions: add or remove swimlanes, reorder them, or configure their settings.
    </Tip>
  </Step>

  <Step title="Add swimlane">
    1. Choose the desired location for the new swimlane (above or below existing lanes)
    2. Click the **add swimlane icon** to create the new swimlane
    3. Give the swimlane a descriptive name (e.g., "Front Office", "Approver", "Back Office")
  </Step>

  <Step title="Configure permissions">
    After creating a swimlane, configure which roles can access it in the **Permissions** section of process settings.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/swimlane_permissions.png)
</Frame>

For more details about access management, check the following sections:

<CardGroup>
  <Card title="User roles management - Swimlanes" href="../../platform-deep-dive/user-roles-management/swimlanes" icon="file" />

  <Card title="Configuring access roles for processes" href="../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes" icon="file" />
</CardGroup>

## Configure process settings

The Settings panel provides configuration options organized across five tabs. To access settings, click the settings icon in the left sidebar.

### Set your process name

Configure the unique identifier for your process definition in the **Process Name** tab.

* **Process definition name**: The unique name for your process

<Info>
  Name can only contain letters, numbers and the following special characters: `[ ] ( ) . _ -`
</Info>

**Best practices for naming**:

* Use descriptive names that clearly identify the process purpose.
* Follow a consistent naming convention across your organization.
* Use underscores or hyphens instead of spaces.
* Keep names concise but meaningful (for example, `Customer_Onboarding` or `Loan_Application`).

### Configure general settings

Use the **General** tab to configure platform settings, reporting options, process data, and expiry time.

<Frame>
  ![General settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/general_settings.png)
</Frame>

#### Select your deployment platform

Choose the deployment target for your process. This setting affects configuration options in Navigation Areas, UI Designer, and Misconfigurations.

**Available platforms**:

* **Web Only**: Use this option when your navigation areas are defined exclusively for web. The process is optimized for web usage and doesn't provide the same functionality on mobile devices.
* **Mobile Only**: Use this option when your navigation areas are defined only for mobile. The process uses mobile-specific features and provides an optimal mobile experience.
* **Omnichannel**: Use this option when your process has navigation areas defined for both web and mobile platforms. This ensures users have a consistent experience regardless of their platform.

<Info>
  Navigation Areas, UI Designer and misconfigurations will be affected by this setting.
</Info>

<Info>
  By default, new processes are set to **Web Only**. This ensures that they are initially optimized for web-based usage, providing a starting point for most users and scenarios.
</Info>

#### Enable read-only access

Allow users to view and navigate through your process definition without modifying data or triggering actions.

<Frame>
  ![Read-only configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/read_nonly_enable.png)
</Frame>

When you enable this setting, you unlock additional customization capabilities in Process Designer and UI Designer, letting you configure read-only access at the process level.

**When to use read-only access**:

* **Supervision and oversight**: Let supervisors review process instances without making changes.
* **Audit and compliance**: Let auditors view process data and history without risk of modification.
* **Information sharing**: Let stakeholders view process status without granting edit permissions.
* **Training and demo**: Show process flows and data to trainees without allowing changes.

**How to configure read-only access**:

1. Enable "Allow Read-Only Process Configuration" in the General settings tab.
2. Configure read-only permissions at the swimlane level in the Permissions tab.
3. Use permission-based expressions in UI Designer to control element visibility and interaction.
4. Enable or disable the toggle at the node level to configure read-only access for specific nodes.

<Info>
  Read-only access allows users to navigate through process screens and see the full context without the ability to modify data or execute actions. This is useful for oversight, auditing, and information sharing scenarios.
</Info>

<Warning>
  **Important**: Read-only configuration must be set at the process level first, then configured per swimlane in the Permissions tab. Hide and disable conditions configured in UI Designer still apply to read-only users.
</Warning>

<Card title="Permission-based expressions" href="./permission-based-expressions" icon="shield-check">
  Learn how to configure granular read-only access control
</Card>

#### Enable reporting

Toggle **Use process in reporting** to include the process in reporting via the Reporting plugin.

#### Configure general data

Use general data to display notifications, warnings, or informational content immediately when a process starts.

**When to use general data**

General data is useful for:

* **Supervision messages**: Display important notices about account supervision or approval requirements.
* **Document generation status**: Show immediate feedback about document processing.
* **Process-level notifications**: Present critical information that needs to be visible from the start.
* **Banner messages**: Display persistent notifications at the top of the process interface.

<Warning>
  General data is not intended for Server-Sent Events (SSE) updates. It provides data immediately available in the process start response, ensuring notifications appear before any real-time updates occur.
</Warning>

**Example configuration**

```json theme={"system"}
{
  "notifications": [
    {
      "identifier": "Supervision",
      "show": "true", 
      "componentIdentifier": "MESSAGE",
      "displayOptions": {
        "flowxProps": {
          "text": "Account opening requires supervision. The client's account and products will be active after receiving necessary approvals.",
          "messageType": "warning"
        }
      }
    }
  ]
}
```

<Tip>
  When you configure general data notifications, ensure the message field contains the actual text to display. Set the `messageType` property to `success`, `warning`, `error`, or `info` to apply the correct styling.
</Tip>

#### Set expiry time

You can configure an expiry time expression on a process definition to specify when the process expires.

| **Example**               | **Expression**         | **Explanation**                                                                                                         |
| ------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Daily Expiry at Midnight  | `0 0 0 * * ?`          | Sets the process to expire at 00:00 (midnight) every day. The `?` is used in the day-of-week field to ignore its value. |
| Hourly Expiry on Weekdays | `0 0 9-17 * * MON-FRI` | Sets the process to expire at the start of each hour between 9 AM and 5 PM on weekdays (Monday to Friday).              |
| Expiry After a Duration   | `PT3M22S`              | Sets the process to expire after a duration of 3 minutes and 22 seconds from the start, using **ISO 8601 format**.      |

<Tip>
  FlowX.AI supports Spring cron expressions. They  **must always include six fields**: `seconds`, `minutes`, `hours`, `day of month`, `month`, and `day of week`.\
  This differs from traditional UNIX cron, which uses only five fields. Be sure to include the `seconds` field in Spring cron expressions to avoid errors.
</Tip>

<Info>
  The cron expression format should include seconds (0), minutes (0), hours (0), and then wildcards for the day, month, and day of the week fields. The `?` sign in the day-of-week field is used when the day-of-month field is already specified (or ignored in this case).
</Info>

<Info>
  You can use both ISO 8601 duration format (`PT3M22S`) and cron expressions (`0 0 0 * * ?`, `0 0 9-17 * * MON-FRI`) to define `expiryTime` expressions for process definitions.
</Info>

For more information about **Cron Expressions** and **ISO 8601** formatting, check the following section:

[Timer Expressions](../node/timer-events/timer-expressions)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/proc_general_settings.png)
</Frame>

### Set permissions

Use the **Permissions** tab to configure role-based access control for each swimlane in your process.

<Frame>
  ![Permissions settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/swm_prmsn.png)
</Frame>

After you define roles in your identity provider solution (for example, Keycloak), they become available for configuring swimlane access in the process definition settings.

#### Configure swimlane permissions

<Steps>
  <Step title="Select swimlane">
    Choose the swimlane you want to configure from the dropdown menu.
  </Step>

  <Step title="Add roles">
    1. Click **Add Role** to assign permissions
    2. Select the role from the dropdown
    3. Choose permission types: **Execute**, **Self Assign**, **View**
  </Step>

  <Step title="Configure multiple executors">
    Toggle **Allow Multiple Swimlane-Executors** to enable multiple users with different roles to work concurrently on the same process instance within the same swimlane.

    <Info>
      When enabled, permissions can be configured at UI Element level in User Tasks from the selected swimlane, allowing granular control over who can see and interact with specific UI components.
    </Info>
  </Step>
</Steps>

#### Default permissions

When you create a new swimlane, it comes with two default permissions:

* **Execute**: Allows users to perform actions in the swimlane
* **Self-assign**: Enables users to assign tasks to themselves

Additional permissions can be added manually based on your requirements.

<Card title="Configuring access rights for processes" href="../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes" />

<Card title="Permission-based expressions" href="./permission-based-expressions" icon="key" />

### Integrate with Task Manager

Use the **Task Management** tab to configure integration with the Task Manager plugin for task tracking and management.

<Frame>
  ![Task management settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/tsk_mngmnt_settings.png)
</Frame>

#### Available configuration options

**Use process in task management**

Toggle this option to enable integration with the Task Manager system.

When you enable this option, the process becomes available for managing tasks within Task Management. This allows data, tasks, and status updates to flow between the process and Task Manager.

**Container App URL**

The Container App URL is the endpoint that directs users to the specific application instance where your process runs.

The URL serves as a reference point for accessing and managing tasks directly from Task Manager. It follows this format:

```
{baseURL}/appId/buildId/processes/resourceId/instance
```

You can:

* Define the URL dynamically using configuration parameters (for example, `${genericParameter}`).
* Set the URL at the process data level using business rules.

**Example URL**:

```
https://demo-angular.devmain.flowxai.dev/
```

**Keys to send to Task Manager**

Specify the data fields (keys) from your process that are sent to Task Manager for indexing and display. Configure these keys on a separate interface.

<Tip>
  **Important considerations**:

  * Keys must exist in the process data model
  * Keys need re-indexing if their type or structure is updated
  * Only enable Task Manager integration if you need task-level tracking
  * This adds overhead, so use selectively for business-critical processes
</Tip>

<CardGroup>
  <Card title="Task Management" href="../../platform-deep-dive/core-extensions/task-management/task-management-overview" icon="list-check">
    Learn more about Task Manager configuration
  </Card>

  <Card title="Task Management Localization" href="../../platform-deep-dive/core-extensions/task-management/task-management-localization" icon="language">
    Localize Task Management in 34+ languages
  </Card>
</CardGroup>

### Configure data search

Use the **Data Search** tab to configure which process data keys are indexed for searching and filtering process instances.

<Frame>
  ![Data Search settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/settings_data_search_tab.png)
</Frame>

#### Index search keys

The **Search Key Indexing** section lets you define which process data fields are searchable. These indexed keys enable efficient searching and filtering of process instances in the Active Process view.

**How to configure search keys**:

1. Click the **+** button to add a new search key.
2. Enter the key path (for example, `application.client.firstName`).
3. Save your changes to apply the indexing configuration.

**Key path format requirements**:

* Use dot notation to access nested fields: `parent.child.fieldName`.
* Keys must match your data model structure exactly.
* Matching is case-sensitive.

**Example key paths**:

* `application.client.firstName`
* `application.client.lastName`
* `application.status`
* `application.dateOfBirth`

<Tip>
  **Process Data Keys**: These are paths or fields in the process definition that store relevant data. For example, `application.client.firstName` corresponds to a field capturing the first name within the client object.
</Tip>

<Warning>
  **Re-indexing required**: After updating the data model structure, re-index the keys in the Search indexing tab to ensure accurate searching and filtering. Indexing can take several minutes for environments with many process instances.
</Warning>

<Info>
  **Performance consideration**: Only index keys you actually need for searching. Excessive indexing can impact performance. Focus on fields commonly used for filtering and searching process instances.
</Info>

## Apply best practices

Follow these guidelines to create well-structured, maintainable process definitions.

### Follow configuration standards

Apply these best practices when configuring your process definitions:

**Platform selection**:

* Choose **Web Only** for desktop-focused applications with complex interactions.
* Choose **Mobile Only** for mobile-first experiences optimized for touch.
* Choose **Omnichannel** only when you need both platforms. Maintain separate processes when platform requirements diverge significantly.

**Naming and organization**:

* Use descriptive, consistent names that clearly identify the process purpose.
* Follow a naming convention like `[Department]_[Function]_[Action]` (for example, `HR_Onboarding_NewEmployee`).
* Avoid special characters beyond the allowed set: `[ ] ( ) . _ -`.
* Keep process names under 50 characters for better readability in lists.

**Data model design**:

* Define your data model structure before building process flows.
* Use meaningful key names that describe the data they contain.
* Organize related data under common parent keys (for example, `customer.firstName` and `customer.lastName`).
* Include example values in the data model to help with development and testing.
* Avoid deeply nested structures—limit nesting to 3-4 levels for better performance.

### Configure swimlanes effectively

**Swimlane best practices**:

* Create swimlanes that mirror your organizational structure or process ownership.
* Assign clear, descriptive names to swimlanes (for example, "Front Office", "Back Office", or "Supervisor").
* Configure appropriate permissions for each swimlane (execute, view, self-assign).
* Enable **Allow multiple executors** when multiple users with different roles need concurrent access.
* Limit the number of swimlanes—too many can make processes difficult to visualize. Aim for 3-5 maximum.

<Card title="Permission-based expressions" href="./permission-based-expressions" icon="key">
  Learn advanced permission configuration for granular access control
</Card>

### Optimize performance

**Settings that affect performance**:

* **Expiry time**: Set appropriate expiry times to prevent stale process instances from accumulating.
* **Task management integration**: Only enable when needed—it adds overhead for task tracking.
* **Reporting integration**: Enable selectively for business-critical processes that require analytics.
* **Search indexing**: Index only the keys you need for searching—excessive indexing affects performance.
* **General data**: Keep general data lightweight—it loads on every process start.

**Data model optimization**:

* Don't store large binary data in the process data model.
* Use references to external systems for large files or documents.
* Clean up temporary data that's no longer needed as the process progresses.

### Follow security best practices

<Warning>
  Apply these security best practices:

  * **Never include sensitive data** in process names or descriptions.
  * **Use role-based permissions properly**: Don't grant execute permissions to roles that shouldn't start processes.
  * **Configure swimlane permissions carefully** to ensure data privacy.
  * **Enable Task Manager integration only** for processes where users need task-level visibility.
  * **Use environment-specific configuration parameters** for sensitive values like API endpoints.
  * **Set appropriate expiry times** to ensure processes don't remain active indefinitely.
  * **Review permission-based expressions** to ensure UI elements hide sensitive data from unauthorized users.
</Warning>

### Configuration checklist

Before deploying a process definition, verify:

<Steps>
  <Step title="Basic Configuration">
    * [ ] Process name is descriptive and follows naming conventions
    * [ ] Platform selection (Web/Mobile/Omnichannel) matches your deployment target
    * [ ] Data model is defined with clear, meaningful key names
  </Step>

  <Step title="Permissions">
    * [ ] Swimlanes are configured with appropriate roles
    * [ ] Execute permissions are assigned to correct user roles
    * [ ] Self-assign permissions are configured where needed
    * [ ] Permission-based expressions are tested with different user roles
  </Step>

  <Step title="Integrations">
    * [ ] Task Manager integration enabled only if required
    * [ ] Application URL configured correctly for Task Manager
    * [ ] Keys to send to Task Manager are defined
    * [ ] Reporting integration enabled only if needed
    * [ ] Search indexing configured for relevant keys
  </Step>

  <Step title="Advanced Settings">
    * [ ] Expiry time expression set appropriately (if needed)
    * [ ] General data configured for initial notifications (if needed)
    * [ ] Audit log reviewed for recent changes
  </Step>
</Steps>

## Manage process versions

Process definitions are versioned as part of projects, providing comprehensive change management.

### Understanding versioning

<Info>
  Process definitions in FlowX.AI are versioned at the **project level**, not individually. This ensures all related resources stay synchronized.
</Info>

**Version types**:

* **Draft versions**: Work-in-progress changes that you can edit freely.
* **Committed versions**: Finalized snapshots that become immutable.
* **Branches**: Parallel development paths for different features or environments.
* **Version comparison**: Tools to compare settings and configurations across versions.

### Make changes to process definitions

<Steps>
  <Step title="Edit in draft">
    Process definitions can only be edited when part of a draft project version. If you need to modify a committed process:

    1. Create a new draft version of your project
    2. Make your changes to the process definition
    3. Test thoroughly
    4. Commit the project version
  </Step>

  <Step title="Commit changes">
    When you commit a project version:

    * The process definition becomes immutable
    * It's available for inclusion in builds
    * All settings are frozen at that point in time
  </Step>

  <Step title="Deploy to environments">
    Create a build from the committed version and deploy it to your target environments. The deployed process definition becomes active and can create process instances.
  </Step>
</Steps>

<CardGroup>
  <Card title="Versioning" href="../../projects/managing-applications/versioning" icon="code-branch">
    Detailed guide to project versioning
  </Card>

  <Card title="Builds and deployment" href="../../projects/runtime/builds" icon="rocket">
    Learn about building and deploying processes
  </Card>
</CardGroup>

### Understand the impact on running instances

<Warning>
  Changes to a process definition don't affect running process instances. Running instances continue using the version of the process definition that was active when they started.
</Warning>

**What this means**:

* You can safely deploy new process definition versions without affecting active users.
* Long-running processes complete using their original definition.
* New process instances use the latest deployed version.
* To apply changes to running instances, you need to migrate them (typically not recommended).

## Troubleshoot common issues

This section covers common issues when configuring process definitions and how to resolve them.

<AccordionGroup>
  <Accordion title="Process won't commit">
    **Symptoms**: You can't commit project version or get errors when trying to save changes.

    **Common causes and solutions**:

    * **Validation errors**: Review process designer warnings and fix all configuration issues.
    * **Missing required nodes**: Ensure your process has at least one start node and one end node.
    * **Invalid expressions**: Check all business rules, cron expressions, and permission expressions for syntax errors.
    * **Permission issues**: Verify you have commit permissions for the project.
    * **Uncommitted dependencies**: Ensure all referenced subprocesses and workflows are also committed.

    <Tip>
      Check the validation warnings panel in the Process Designer before you try to commit.
    </Tip>
  </Accordion>

  <Accordion title="Process instances won't start">
    **Symptoms**: Users get errors when trying to start a new process instance.

    **Common causes and solutions**:

    * **Process not published**: Verify the process is part of an active build deployed to the environment.
    * **Missing permissions**: Check that user roles have execute permission on the process start node.
    * **Invalid start node configuration**: Review the start node settings and start conditions.
    * **Multiple start nodes without conditions**: If you have multiple start nodes, ensure each has a unique start condition.
    * **Environment mismatch**: Confirm the process is deployed to the correct environment.

    <Card title="Failed process start errors" href="../../projects/runtime/active-process/failed-process-start" icon="triangle-exclamation" />
  </Accordion>

  <Accordion title="Task Manager integration not working">
    **Symptoms**: The process doesn't appear in Task Manager or tasks aren't created.

    **Common causes and solutions**:

    * **Integration not enabled**: Enable "Use process in task management" in the General settings tab.
    * **Application URL misconfigured**: Verify the application URL format is correct and uses valid parameters.
    * **Keys not configured**: Define which keys should be sent to Task Manager.
    * **Indexing issues**: Keys may need re-indexing after data model changes.
    * **Task Manager service unavailable**: Check platform status to ensure the Task Manager service is running.
  </Accordion>

  <Accordion title="Search/filtering not working correctly">
    **Symptoms**: You can't find process instances using search, or filters return incorrect results.

    **Common causes and solutions**:

    * **Keys not indexed**: Add the required keys to the Data Search configuration.
    * **Data model changes not re-indexed**: After changing the data model structure, re-index search keys.
    * **Incorrect key paths**: Verify the key paths match your actual data model structure and check for typos.
    * **Case sensitivity**: Search is case-sensitive—ensure queries match the actual data casing.
    * **Indexing delay**: Recent process instances may not be immediately searchable—allow time for indexing.

    <Info>
      Re-indexing can take several minutes for environments with many process instances.
    </Info>
  </Accordion>

  <Accordion title="Expiry time not working as expected">
    **Symptoms**: Processes expire too early, too late, or not at all.

    **Common causes and solutions**:

    * **Cron expression errors**: Verify your cron expression includes all six required fields (seconds, minutes, hours, day, month, day of week).
    * **Time zone issues**: Cron expressions use server time zone—account for time zone differences.
    * **ISO 8601 format errors**: Check the duration format is correct (for example, `PT3M22S` for 3 minutes 22 seconds).
    * **Expiry not enabled**: Confirm the expiry time expression is configured in settings.
    * **Process already expired**: Processes past expiry time may not be startable.

    <Card title="Timer expressions" href="../node/timer-events/timer-expressions" icon="clock" />
  </Accordion>

  <Accordion title="Platform-specific configuration issues">
    **Symptoms**: Navigation areas or UI elements don't appear on expected platforms.

    **Common causes and solutions**:

    * **Incorrect platform setting**: Verify "Available Platforms" matches your navigation area configuration.
    * **Web Only with mobile navigation**: If set to Web Only, mobile navigation areas aren't available.
    * **Platform mismatch with deployment**: Ensure the deployed build targets the correct platform (web renderer or mobile renderer).
    * **Navigation areas not configured**: Check that navigation areas exist for the selected platform.
    * **UI Designer platform mismatch**: Verify UI elements are configured for the same platform as the process.
  </Accordion>

  <Accordion title="Permission configuration errors">
    **Symptoms**: Users can't access the process, see unexpected UI elements, or can't perform actions.

    **Common causes and solutions**:

    * **Missing role assignments**: Verify users have required roles in your identity provider (for example, Keycloak).
    * **Swimlane permissions not configured**: Check that appropriate permissions (execute, view, self-assign) are set.
    * **Permission expressions incorrect**: Review permission-based expressions for syntax errors.
    * **Multiple executors not enabled**: If you need multiple users in the same swimlane, enable "Allow multiple executors".
    * **Cross-swimlane reference issues**: When referencing users from other swimlanes, store them in process data.

    <Card title="Permission-based expressions" href="./permission-based-expressions" icon="shield-check" />
  </Accordion>
</AccordionGroup>

### Get help with other issues

If you continue experiencing issues:

1. Check the **audit log** to see recent changes that might have caused problems.
2. Review **process validation warnings** in the Process Designer.
3. Test with a **simple process** to isolate whether the issue is process-specific or environmental.
4. Check **Platform Status** to ensure all FlowX services are healthy.
5. Review **logs** in your FlowX.AI deployment for detailed error messages.

<Card title="Platform status monitoring" href="../../flowx-designer/overview#platform-status" icon="signal-bars">
  Check the health of FlowX services
</Card>

## Related resources

<CardGroup>
  <Card title="Process Designer" href="./process" icon="pen-ruler">
    Learn about the canvas and design interface
  </Card>

  <Card title="BPMN Nodes" href="../node/node" icon="diagram-project">
    Complete guide to all node types
  </Card>

  <Card title="Data Model" href="./data-model" icon="database">
    Managing process data structures
  </Card>

  <Card title="Subprocess" href="./subprocess" icon="folder-tree">
    Creating reusable process components
  </Card>

  <Card title="Navigation Areas" href="./navigation-areas" icon="compass">
    Configuring user navigation
  </Card>

  <Card title="User Roles Management" href="../../platform-deep-dive/user-roles-management/swimlanes" icon="users">
    Advanced swimlane configuration
  </Card>
</CardGroup>


# Subprocess management
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/subprocess

Learn how to configure, start, and execute subprocesses efficiently within your process flow.

Subprocesses are smaller process flows triggered by actions in the main process. They can inherit some process parameter values from the parent process and communicate with front-end apps using the same connection details as their parent process.

## Overview

Subprocesses can be started in two modes:

* **Asynchronous**: Execute alongside the parent process without delaying it.
* **Synchronous**: The parent process waits until subprocesses are finished before advancing.

## Knowledge for mobile

Screens rendered on mobile (Pages, Steps) are kept inside a navigation history which the user can go back to.

Subprocesses started from Call activity nodes share the navigation history (stack) with the main processes. When a subprocess is finished, it's UI is cleared from the navigation history. Design your BPMN processes in accordance with your business and ux needs.

Subprocesses started from User task nodes, should only be used for secondary flows that are displayed to the user, which should be rendered in modals. These flows should be optional event handlers. If the journey is mandatory, then consider moving it into call activities.

### Navigation back-stack behavior on mobile

This is the mental model for how the mobile back stack works across Pages, Modals, and Call Activity subprocesses.

**Pages and Steps.** Every Page or Step the user reaches is pushed onto the native back stack. The OS back button, gesture back, and any in-app back button pop the last entry. Users can back-navigate all the way to the first screen of the flow.

**Modals.** Modals are never kept in the back stack. When the flow advances past a modal onto the next screen, the modal is popped before the new entry is pushed. This is why you cannot back-navigate into a modal: by the time anything has been pushed after it, the modal is already gone.

**Modal internal navigation.** The recommended way to have back-navigation *between* modal-rendered screens is a single **Modal** navigation area with multiple User Tasks inside. Mobile renders each User Task as one screen (1 UT = 1 screen), with a built-in back button between them. Separate modal navigation areas cannot be stacked or linked this way.

**Call Activity subprocesses.** A Call Activity subprocess shares the same back stack as the parent process. While the subprocess runs, its Pages and Steps are pushed onto the shared stack alongside the parent's. The user can back-navigate through them normally.

**Call Activity finish.** When the subprocess finishes, the user is returned to the last screen of the parent process (where the Call Activity was started from). The subprocess's screens are cleared from the back stack, so the user cannot return to them after completion.

**Modals and Call Activity interact as expected.** A modal inside a Call Activity is not special: the OS auto-pops it on forward navigation, and the subprocess-finish clearing operates on whatever Pages or Steps remain. The user never lands on a modal via back, regardless of whether it was inside the parent process or the subprocess.

***

## Subprocess design rules

<Warning>
  **Hard rules for subprocesses:**

  * **Avoid nesting a UI subprocess under a headless one.** A subprocess with no UI should not contain a subprocess with UI. The hierarchy is harder to read and maintain. See [Process design principles](./design-principles#avoid-nesting-a-ui-subprocess-under-a-headless-one) for the full rationale.
  * **A child subprocess must not dismiss its parent.** A subprocess of a subprocess should not end the lifecycle of the parent subprocess. Completion of a grandchild should only resolve the grandchild.
  * **UI subprocesses must start synchronously.** A subprocess with UI should never start in async mode. Async UI subprocesses race with the parent's token advance and get dismissed before the user can complete them.
  * **Starting a subprocess from a user task action.** Use modal-only navigation for the entry point and keep the starting action **optional**. Mandatory UT actions that launch subprocesses block the flow if the subprocess cannot start.
  * **Call Activity subprocesses with Pages or Steppers appear in mobile back-nav.** Their screens land in the native back stack. Design flows so that back-navigation actions land on **meaningful states**, not orphaned or mid-step screens.
</Warning>

***

## Configuring & starting subprocesses

Design subprocesses within the FlowX.AI Designer, mirroring the main process structure.

<Steps>
  <Step title="Start Subprocess Action">
    * Within user tasks or task nodes.
  </Step>

  <Step title="Call Activity node">
    * Custom node type in the main process.
  </Step>

  <Step title="Start Embedded Subprocess node">
    * Using the corresponding node.
  </Step>
</Steps>

### Parameter inheritance

<Info>
  Available for **Start Subprocess** action and **Call Activity** node.
</Info>

By default, subprocesses inherit all parent process parameter values. Configure inheritance by:

* **Copy from Current State**: Select keys to copy.
* **Exclude from Current State**: Specify keys to ignore.

Sub-processes can also have an [**Append Params to Parent Process**](../actions/append-params-to-parent-process) action  configured inside their process definitions which will append their results to the parent process parameter values.

<Card title="Append Params to Parent Process" href="../actions/append-params-to-parent-process" icon="file" />

## Executing subprocesses

Define subprocess execution mode:

* **Asynchronous/Synchronous**: Set the `startedAsync` parameter accordingly.

In synchronous mode, subprocesses notify completion to the parent process. The parent process then resumes its flow and handles subprocess data.

## How data flows between subprocess and parent

When a subprocess needs to send data back to the parent process, FlowX provides several mechanisms. Choosing the right one depends on whether you need data in the parent UI, the parent data model, or both.

### Data return mechanisms

| Mechanism                                                                                  | What it does                                                                               | Parent data model |          Parent UI         | When to use                                                                                         |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | :---------------: | :------------------------: | --------------------------------------------------------------------------------------------------- |
| [**Append Params to Parent Process**](../actions/append-params-to-parent-process)          | Copies specified keys from subprocess into the parent process data model                   |        Yes        | No (until next UI refresh) | Business logic in the parent needs subprocess results (conditions, validations, downstream actions) |
| [**Send data to user interface**](../actions/send-data-to-user-interface) (target: Parent) | Pushes data to the parent process UI via SSE                                               |         No        |       Yes (real-time)      | Real-time UI updates while the subprocess runs (progress indicators, live previews)                 |
| **Call Activity output key** (sync mode)                                                   | Automatically returns subprocess data under a configured key when the subprocess completes |        Yes        |             No             | Sync subprocesses where the parent waits for results                                                |
| **Embedded subprocess**                                                                    | Shares the parent data model directly, no data transfer needed                             |       Shared      |           Shared           | Simple subprocess logic that operates on the same data                                              |

### Common patterns

**"I need data in both the parent data model and the parent UI"**
Use both actions: configure **Append Params to Parent Process** to persist the data, and **Send data to user interface** (target: Parent) to push the update to the UI immediately.

**"My subprocess has a throw event before the end node — do output parameters still get sent?"**
Output parameters configured on the Call Activity node are sent when the subprocess token reaches the **End** node. If the subprocess ends via a throw event before reaching End, the output parameters are not automatically returned. Use **Append Params to Parent Process** before the throw event to ensure data reaches the parent.

### Message format example

When using **Send data to user interface** to push data to the parent UI, the message body follows this format:

```json theme={"system"}
{
  "application": {
    "clientName": "${application.client.firstName}",
    "status": "verified"
  }
}
```

This data is sent via SSE and rendered in the parent process UI, but is **not** stored in the parent process data model.

***

## Additional resources

<CardGroup>
  <Card title="Call activity node" href="../node/call-subprocess-tasks/call-activity-node" icon="link" />

  <Card title="Start a subprocess action" href="../actions/start-subprocess-action" icon="link" />

  <Card title="Start embedded subprocess" href="../node/call-subprocess-tasks/start-embedded-subprocess" icon="link" />

  <Card title="Synchronous Subprocesses course" icon="graduation-cap" href="https://academy.flowx.ai/explore/synchronous-subprocesses-0">
    Academy course covering embedded/call activities, UI updates, and data passing patterns
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**Academy\_Synchronous\_Subprocesses**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/4042b5c8-9cbe-4b0b-9cef-668438ee0fa3/config/e79c098a-22a9-4bb6-8841-4e45861503d9/processes) project for working examples of subprocess data passing, call activities, and embedded subprocesses.
</Tip>


# UI Designer best practices
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/best-practices

Best practices for creating effective user interfaces using FlowX.AI UI Designer, based on established design principles and platform capabilities.

## UI Designer best practices in FlowX.AI

When designing user interfaces with FlowX.AI UI Designer, following established best practices ensures consistent, usable, and effective user experiences.

## Design principles

Based on FlowX.AI documentation for creating user interfaces:

<CardGroup>
  <Card title="Consistent Styling" icon="palette">
    **Use consistent styling across all screens** for a cohesive user experience.

    Use platform-specific overrides strategically while maintaining visual consistency.
  </Card>

  <Card title="Logical Grouping" icon="object-group">
    **Group related inputs within logical sections or cards**.

    Use Cards and Containers to organize content and create visual hierarchy.
  </Card>

  <Card title="Proper Validation" icon="check">
    **Implement proper validation** to prevent errors and guide users.

    Use available validators: required, custom, and conditional validation.
  </Card>

  <Card title="Clear Feedback" icon="message">
    **Provide clear feedback** on actions with success and error messages.

    Use event handlers to handle user interactions appropriately.
  </Card>
</CardGroup>

## Component usage guidelines

### Form elements best practices

<AccordionGroup>
  <Accordion title="Input Fields" icon="input-pipe">
    **Configuration**:

    * Use clear, descriptive labels
    * Implement appropriate validation (required, custom)
    * Configure hide/disable expressions for dynamic behavior
    * Add helper text for complex requirements

    **Available Properties**:

    * Label and placeholder text
    * Validation rules (required, custom)
    * Hide and disable expressions
    * Platform-specific overrides
  </Accordion>

  <Accordion title="Selection Components" icon="square-check">
    **Select Component**:

    * Use for dropdown menus and single selections
    * Configure options with proper labels and values
    * Implement CHANGE event handlers for dependent fields
    * Use disabled options feature for conditional availability

    **Radio Buttons**:

    * Best for 2-4 exclusive options
    * Use when all options need to be visible

    **Checkboxes**:

    * Use for multiple selections or single yes/no choices
    * Configure CHANGE events for dynamic interactions
  </Accordion>

  <Accordion title="Action Components" icon="hand-pointer">
    **Buttons**:

    * Use descriptive labels that indicate the action
    * Configure appropriate event handlers (Process Actions, Data Operations)
    * Consider platform-specific button styles

    **File Upload**:

    * Clearly indicate accepted file types
    * Provide appropriate feedback during upload process
    * Consider platform limitations for mobile devices
  </Accordion>
</AccordionGroup>

### Layout best practices

<Tabs>
  <Tab title="Linear Layout">
    **When to Use**: Simple, sequential content flow

    **Configuration**:

    * **Direction**: Choose Horizontal for row layout, Vertical for column layout
    * **Justify**: Control main axis alignment (Start, Center, End, Space Between, etc.)
    * **Align**: Control cross axis alignment (Start, Center, End, Stretch)
    * **Gap**: Set appropriate spacing between elements
    * **Wrap**: Enable for responsive behavior when needed

    **Best For**:

    * Form layouts
    * Content that flows in one direction
    * Mobile-first designs
  </Tab>

  <Tab title="Grid Layout">
    **When to Use**: Complex, multi-dimensional layouts

    **Benefits**:

    * Better control over 2D layouts
    * Responsive design capabilities
    * Suitable for dashboard-style interfaces

    **Considerations**:

    * More complex to configure than linear layouts
    * Test across platforms for consistent behavior
  </Tab>
</Tabs>

## Platform-specific best practices

### Web Platform

<Steps>
  <Step title="Navigation Design">
    **Navigation Types**:

    * Use **Single Page Form** for displaying all User Tasks on the same page
    * Use **Wizard** navigation for step-by-step processes
    * Configure actions properly for smooth navigation flow
  </Step>

  <Step title="Zone Configuration">
    **Web-Specific Features**:

    * Utilize zones with headers and footers (web-only feature)
    * Implement proper navigation hierarchy
    * Use cards to guide users through content on single-page forms
  </Step>

  <Step title="Layout Optimization">
    **Screen Real Estate**:

    * Take advantage of larger screen sizes
    * Use appropriate justify and align settings for content distribution
    * Consider horizontal layouts for better space utilization
  </Step>
</Steps>

### Mobile Platforms (iOS & Android)

<AccordionGroup>
  <Accordion title="Screen Configuration" icon="mobile">
    **Mobile-Specific Properties**:

    * Configure **Screen Title** for navigation bar display (Card component when used as root)
    * Set **Scrollable** property appropriately (iOS-specific)
    * Use platform overrides for shorter titles and mobile-optimized content

    **Limitations**:

    * Zones with headers and footers are not supported
    * Navigation features are more limited compared to web
  </Accordion>

  <Accordion title="Content Adaptation" icon="mobile-signal-out">
    **Content Strategy**:

    * Use shorter titles and labels for mobile displays
    * Consider touch interaction patterns
    * Ensure content fits within mobile screen constraints
    * Test with realistic content lengths
  </Accordion>
</AccordionGroup>

## Dynamic behavior best practices

### Hide and Disable Expressions

<Tabs>
  <Tab title="Hide Expressions">
    **Purpose**: Control element visibility based on conditions

    **Implementation**:

    * Use JavaScript expressions that evaluate to true/false
    * Reference process data store keys for dynamic evaluations
    * Configure in Settings → Platform → Overrides → Expressions → Hide

    **Common Use Cases**:

    * Show/hide fields based on user selections
    * Display different content for different user roles
    * Adapt interface based on process state
  </Tab>

  <Tab title="Disable Expressions">
    **Purpose**: Make elements non-interactive while keeping them visible

    **Best Practice**: Ensure disabled fields have the same expression configured under hide expressions for consistency.

    **Usage**: Disable form fields based on validation state or user permissions
  </Tab>
</Tabs>

### Conditional Styling

**Available For**: Text, Link, and Container elements

<Steps>
  <Step title="Configuration">
    1. Select a **Text**, **Link**, or **Container** element
    2. Navigate to the **Styles** tab
    3. Locate the **Conditional Styling** section
    4. Click the **➕** icon to add expressions and effects
    5. Use the **JS Editor** to configure expressions
  </Step>

  <Step title="Structure">
    **Condition**: String expression evaluated similarly to hide/disable expressions
    **Overrides**: Key-value map defining property-value pairs to apply
  </Step>

  <Step title="Best Practices">
    * Use real-time data evaluation for responsive UI updates
    * Handle conflict resolution (latest condition takes precedence)
    * Combine with data-driven expressions for adaptable designs
  </Step>
</Steps>

## Validation best practices

### Available Validators

<AccordionGroup>
  <Accordion title="Required Validator" icon="asterisk">
    **Usage**: Ensure essential fields are completed before form submission

    **Application**: Apply to critical form elements like name, email, or selection fields
  </Accordion>

  <Accordion title="Custom Validator" icon="code">
    **Usage**: Implement complex business logic validation

    **Benefits**: Flexible validation rules specific to your business requirements

    **Configuration**: Use JavaScript expressions for validation logic
  </Accordion>

  <Accordion title="Conditional Validation" icon="badge-check">
    **Usage**: Apply validation based on other field values or process state

    **Examples**: Validate fields only when certain conditions are met
  </Accordion>
</AccordionGroup>

## Event handlers best practices

### Event Configuration

**Common Events**:

* **CHANGE**: Triggered when form element values change
* Use for updating dependent fields, triggering calculations, showing/hiding related content

**Action Types**:

* **Process Actions**: Advance workflow based on user interactions
* **Data Operations**: Update form fields and process data
* **UI Updates**: Show/hide elements dynamically
* **External Calls**: Integrate with external systems

<Tip>
  Configure event handlers to provide immediate feedback and create responsive user experiences.
</Tip>

## Testing and quality assurance

### Platform Testing

<Steps>
  <Step title="Multi-Platform Preview">
    Use the UI Designer's platform switching to preview designs across Web, iOS, and Android platforms.
  </Step>

  <Step title="Responsive Testing">
    Test layouts with different content lengths and screen orientations.
  </Step>

  <Step title="Expression Validation">
    Test hide/disable expressions and conditional styling with various data scenarios.
  </Step>

  <Step title="Navigation Flow">
    Verify wizard navigation and single-page form behaviors work as expected.
  </Step>
</Steps>

### Content Considerations

<CardGroup>
  <Card title="Accessibility" icon="universal-access" href="../../platform-deep-dive/accessibility">
    **Design Considerations**:

    * Use proper labels for form elements
    * Ensure sufficient color contrast
    * Test with assistive technologies
    * Provide alternative text for images

    For details on WCAG 2.1 compliance, keyboard navigation, and screen reader support, see the [Accessibility guide](../../platform-deep-dive/accessibility).
  </Card>

  <Card title="Responsive Design" icon="arrows-rotate">
    **Test Strategy**:

    * Verify layouts work on different screen sizes
    * Test navigation on both mobile and web
    * Ensure content remains readable across platforms
    * Check platform-specific overrides function correctly
  </Card>
</CardGroup>

## Common patterns and solutions

### Navigation areas management

**Copy Navigation Areas**: Use the copy/paste feature to replicate navigation hierarchies between platforms (within the same process definition and environment).

**Area Deletion**: When deleting navigation areas, remember that child areas are also removed, and user tasks are relocated to the User Tasks section.

### Theme and styling management

**Theme Overrides**:

* Customize component appearance to differ from theme settings
* Import/export theme overrides between platforms for consistency
* Use contextual menu options for efficient style management

**Style Copying**: Use copy/paste functionality for styles between compatible components and across platforms.

<Info>
  These best practices are based on actual FlowX.AI capabilities and documentation. Always refer to the latest documentation for the most current features and recommendations.
</Info>


# Platform-specific considerations
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/platform-considerations

Platform-specific configuration, limitations, and best practices for Web, iOS, and Android platforms in FlowX.AI UI Designer.

## Platform-specific configuration

FlowX.AI UI Designer provides platform-specific configuration and styling for components across **Web**, **iOS**, and **Android** platforms. Understanding platform differences and capabilities is essential for creating optimal user experiences.

## Platform overview

### Supported platforms

<CardGroup>
  <Card title="Web" icon="globe">
    **Full Feature Support**

    * Complete navigation area functionality
    * Zones with headers and footers
    * Wizard and single-page navigation
    * All UI component types supported
  </Card>

  <Card title="iOS" icon="mobile">
    **Mobile-Optimized**

    * Basic navigation areas
    * Screen title configuration for navigation bar
    * Scrollable property for root card components
    * Platform-specific property overrides
  </Card>

  <Card title="Android" icon="android">
    **Mobile-Optimized**

    * Basic navigation areas
    * Screen title configuration for navigation bar
    * Platform-specific property overrides
    * Material design considerations
  </Card>
</CardGroup>

## Web platform features

### Navigation capabilities

**Full Navigation Support**: Web platform provides the most comprehensive navigation features.

<AccordionGroup>
  <Accordion title="Zone Navigation" icon="chart-area">
    **Web-Exclusive Features**:

    * Zones with headers and footers
    * Complete navigation hierarchy
    * Advanced navigation patterns

    <Warning>
      Zones with headers and footers are exclusively accessible in web configurations. They are not supported as navigation areas for mobile development.
    </Warning>
  </Accordion>

  <Accordion title="Navigation Types" icon="arrows-split-up-and-left">
    **Single Page Form (Default)**:

    * Web Renderer displays all User Tasks within the same page (in parallel)
    * Use cards to guide users through content
    * Child areas rendered on the same page

    **Wizard Navigation**:

    * Displays one user task at a time
    * Custom Next and Back buttons
    * Child areas presented sequentially
    * Requires proper action configuration
  </Accordion>
</AccordionGroup>

### Component support

**Full Component Library**: Web platform supports all UI component types without restrictions.

## Mobile platform features

### iOS platform specifics

<Tabs>
  <Tab title="Screen Configuration">
    **iOS-Specific Properties**:

    **Screen Title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root)

    **Scrollable Property**: Define the desired behavior of the screen, specifying whether it should be scrollable or not (default: true)

    ```json theme={"system"}
    {
      "screenTitle": "User Profile",
      "scrollable": true
    }
    ```
  </Tab>

  <Tab title="Navigation Limitations">
    **Mobile Navigation Restrictions**:

    * Basic navigation areas only
    * No zones with headers and footers
    * Limited navigation types compared to web
    * Navigation hierarchy displayed beneath platform tabs
  </Tab>

  <Tab title="Component Adaptations">
    **iOS Considerations**:

    * Screen size variations (iPhone, iPad)
    * Touch interaction patterns
    * Platform-specific styling requirements
    * System integration features
  </Tab>
</Tabs>

### Android platform specifics

<AccordionGroup>
  <Accordion title="Screen Configuration" icon="smartphone">
    **Android-Specific Features**:

    **Screen Title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root)

    **Material Design Considerations**: Android components adapt to Material Design principles where applicable
  </Accordion>

  <Accordion title="Device Variations" icon="devices">
    **Android Ecosystem**:

    * Multiple screen sizes and densities
    * Different Android versions
    * Manufacturer-specific customizations
    * Hardware capability variations
  </Accordion>
</AccordionGroup>

## Platform override system

### Configuration hierarchy

<Steps>
  <Step title="Generic Settings">
    **Base Configuration**: Properties available cross-platform (Web, Android and iOS), serving as the default for all platforms.
  </Step>

  <Step title="Platform Overrides">
    **Specific Customizations**: Override generic settings for individual platforms to optimize user experience.
  </Step>

  <Step title="Preview and Testing">
    **Visual Validation**: Preview changes across platforms, keeping in mind that iOS and Android previews are estimates.
  </Step>
</Steps>

### Implementing overrides

To configure platform-specific overrides:

<Steps>
  <Step title="Access Platform Settings">
    From the UI Designer navigation panel, select the **Settings** tab, then select the **desired platform** (Web, iOS, or Android).
  </Step>

  <Step title="Add Override">
    Click the "+" button (next to "Overrides") and select the type of override:

    * **Properties**: Override component properties (e.g., Title, Subtitle, Helper text)
    * **Expressions**: Override hide/show conditions
  </Step>

  <Step title="Configure Value">
    Enter the platform-specific value that differs from the generic setting.
  </Step>

  <Step title="Import/Export">
    Use the import/push functionality to share overrides between platforms when appropriate.
  </Step>
</Steps>

### Available override types

<Tabs>
  <Tab title="Property Overrides">
    **Common Property Overrides**:

    * **Title**: Shorter titles for mobile displays
    * **Subtitle**: Platform-appropriate subtitles
    * **Helper Text**: Context-specific help information
    * **Labels**: Adapted for platform conventions

    **Example Use Case**: Web title "Complete Application Process" → Mobile title "Complete App"
  </Tab>

  <Tab title="Expression Overrides">
    **Hide Expressions**: Platform-specific visibility conditions

    **Use Cases**:

    * Show different content on mobile vs desktop
    * Hide complex features on mobile platforms
    * Adapt to platform-specific user flows
  </Tab>
</Tabs>

## Platform limitations and constraints

### Component availability

| Component Type   | Web | iOS | Android | Notes                                       |
| ---------------- | --- | --- | ------- | ------------------------------------------- |
| Container        | ✅   | ✅   | ✅       | Full support across platforms               |
| Card             | ✅   | ✅   | ✅       | Mobile has additional screen title property |
| Custom           | ✅   | ❌   | ❌       | Web-only component                          |
| Form Elements    | ✅   | ✅   | ✅       | Full support with platform adaptations      |
| Navigation Areas | ✅   | ⚠️  | ⚠️      | Limited on mobile (no headers/footers)      |

<Info>
  ⚠️ = Limited functionality or platform-specific constraints\
  ❌ = Not supported on platform
</Info>

### Navigation limitations

<AccordionGroup>
  <Accordion title="Mobile Navigation Constraints" icon="mobile-screen">
    **Limitations**:

    * No zones with headers and footers on mobile
    * Limited navigation types (no wizard mode on mobile)
    * Simplified navigation hierarchy
    * Basic navigation areas only

    **Workarounds**:

    * Use card-based layouts for mobile organization
    * Implement navigation through event handlers
    * Use platform-specific screen titles
  </Accordion>

  <Accordion title="Cross-Platform Consistency" icon="arrows-rotate">
    **Challenges**:

    * Different navigation capabilities across platforms
    * Varying screen sizes and interaction methods
    * Platform-specific design conventions

    **Solutions**:

    * Use generic settings as baseline
    * Apply strategic platform overrides
    * Test across all target platforms
    * Design for the most constrained platform first
  </Accordion>
</AccordionGroup>

## Platform-specific best practices

### Web platform optimization

<CardGroup>
  <Card title="Navigation Design" icon="sitemap">
    **Use Web Capabilities**:

    * Use full zone navigation with headers/footers
    * Implement wizard navigation for complex flows
    * Take advantage of larger screen real estate
    * Use single-page forms with card organization
  </Card>

  <Card title="Layout Strategy" icon="table-layout">
    **Web-Specific Layouts**:

    * Utilize horizontal space effectively
    * Implement complex grid layouts
    * Support both single-page and wizard navigation
    * Consider desktop interaction patterns
  </Card>
</CardGroup>

### Mobile platform optimization

<Steps>
  <Step title="Screen Space Management">
    **Mobile Constraints**:

    * Smaller screen sizes require condensed content
    * Use shorter titles and labels
    * Prioritize essential information
    * Consider thumb-friendly interaction zones
  </Step>

  <Step title="Platform Integration">
    **Mobile-Specific Features**:

    * Configure screen titles for navigation bars
    * Set appropriate scrollable behavior (iOS)
    * Consider platform design conventions
    * Test on actual devices when possible
  </Step>

  <Step title="Content Adaptation">
    **Mobile Content Strategy**:

    * Use platform overrides for mobile-optimized text
    * Simplify complex interactions
    * Ensure touch targets are appropriately sized
    * Test with realistic content lengths
  </Step>
</Steps>

## Testing across platforms

### Preview limitations

<Info>
  **Important**: The preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view. Actual device testing is recommended for production applications.
</Info>

### Testing Strategy

<AccordionGroup>
  <Accordion title="Platform Switching" icon="arrows-rotate">
    **UI Designer Testing**:

    * Use platform tabs to switch between Web, iOS, and Android views
    * Compare layouts and content across platforms
    * Validate platform overrides are applied correctly
    * Check navigation behavior differences
  </Accordion>

  <Accordion title="Content Validation" icon="check">
    **Cross-Platform Content**:

    * Verify text fits within mobile constraints
    * Test with longest expected translations
    * Ensure critical information is visible on all platforms
    * Validate platform-specific features function correctly
  </Accordion>

  <Accordion title="Functionality Testing" icon="play">
    **Feature Validation**:

    * Test navigation flows on each platform
    * Verify platform-specific components work as expected
    * Validate hide/show expressions across platforms
    * Test conditional styling behavior
  </Accordion>
</AccordionGroup>

## Migration and maintenance

### Platform updates

<Tip>
  **Override Management**: Settings overrides can always be imported/pushed from one platform to another, making it easier to maintain consistency while allowing for platform-specific optimizations.
</Tip>

### Maintenance best practices

<Steps>
  <Step title="Regular Testing">
    Test your interfaces across all target platforms regularly, especially after making changes to generic settings or platform overrides.
  </Step>

  <Step title="Documentation">
    Document platform-specific decisions and overrides to help team members understand the rationale behind platform differences.
  </Step>

  <Step title="Consistency Monitoring">
    Regularly review platform overrides to ensure they still serve their intended purpose and maintain overall design consistency.
  </Step>
</Steps>

<Check>
  Understanding platform-specific considerations helps you create interfaces that work well across all target platforms while taking advantage of each platform's unique capabilities and respecting their constraints.
</Check>


# Screen configuration guide
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/screen-configuration-guide

Learn how to configure screens effectively using FlowX.AI UI Designer with platform-specific settings and navigation areas.

FlowX.AI UI Designer allows you to create rich, interactive user interfaces for your process flows. The UI Designer is available for **User Task** nodes and **Navigation Areas** elements, providing contextual interface design capabilities.

## Platform-specific configuration

FlowX.AI provides platform-specific configuration and styling for components across **Web**, **iOS**, and **Android** platforms.

### Generic vs platform-specific settings

<Tabs>
  <Tab title="Generic Settings">
    **Cross-Platform Properties**: Configure properties available cross-platform (Web, Android and iOS), available for all platforms.

    These settings serve as the base configuration that applies to all platforms unless specifically overridden.
  </Tab>

  <Tab title="Platform-Specific Overrides">
    **Platform-Specific Configuration**: Override generic settings for specific platforms.

    For example, on Android, you might want to change the Card title to a shorter one to better fit mobile screens.
  </Tab>
</Tabs>

### Configuring platform overrides

To override a general property for a specific platform:

<Steps>
  <Step title="Access UI Designer">
    Open the UI Designer and select a UI Element, such as a **Card**.
  </Step>

  <Step title="Access Platform-Specific Settings">
    From the UI Designer navigation panel, select the **Settings** tab, then select the **desired platform** (Web, iOS, or Android).
  </Step>

  <Step title="Perform Override">
    Click the "+" button (next to "Overrides") and select **Properties** -> select the property you want to override (e.g., **Title**), then input your desired value.
  </Step>

  <Step title="Preview Changes">
    Preview your changes in the UI Designer by navigating from one platform to another or by comparing them.
  </Step>
</Steps>

<Tip>
  Settings overrides can always be imported/pushed from one platform to another for consistency across platforms.
</Tip>

<Info>
  Keep in mind that the preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view.
</Info>

## Navigation areas configuration

Navigation areas play a pivotal role in user interface design. They enhance the user experience by providing a structured, organized, and efficient way for users to interact with and explore various features and solutions.

### Navigation types (web only)

<AccordionGroup>
  <Accordion title="Single Page Form (Default)" icon="file">
    **Behavior**: The Web Renderer will display all User Tasks within the same page (in parallel).

    **Best Practices**:

    * Use **Cards** to guide users through the content
    * Apply **Accordions** to cards to collapse each card after validation
    * Maintain a clean UI while displaying multiple user tasks

    **Child Areas**: Rendered on the same page
  </Accordion>

  <Accordion title="Wizard Navigation" icon="arrow-right">
    **Behavior**: The Web Renderer will display one user task at a time, allowing navigation using custom Next and Back buttons.

    **Usage**: Ideal for step-by-step or wizard-style navigation within a page when a page contains more than one User Task.

    **Child Areas**: Presented sequentially

    <Warning>
      It's crucial to configure actions properly to ensure smooth user navigation in wizard mode.
    </Warning>
  </Accordion>
</AccordionGroup>

<Info>
  Navigation types are only available for **Web** platform configurations.
</Info>

### Platform hierarchy

In the navigation panel, the navigation hierarchy is displayed beneath platform tabs:

* **Web Platform**: Full navigation features including zones with headers and footers
* **Mobile Platforms** (iOS & Android): Limited navigation features

<Warning>
  Zones with headers and footers are exclusively accessible in web configurations. They are not supported as navigation areas for mobile development.
</Warning>

## Layout configuration

Layout settings are available for all components that can group other types of elements (for example, **Containers** or **Cards**).

### Linear layout properties

<AccordionGroup>
  <Accordion title="Display Mode" icon="bars">
    **Linear**: Selected by default for arranging child elements in a linear fashion.
  </Accordion>

  <Accordion title="Direction" icon="arrows-up-down">
    * **Horizontal**: Aligns child elements horizontally in a row
    * **Vertical**: Aligns child elements vertically in a column
  </Accordion>

  <Accordion title="Justify" icon="align-justify">
    Controls the alignment of child elements along the main axis (the direction set by Horizontal or Vertical):

    * **Start**: Aligns elements at the start of the container
    * **Center**: Centers elements along the main axis
    * **End**: Aligns elements at the end of the container
    * **Space Between**: Distributes elements evenly with space between them
    * **Space Around**: Distributes elements with space around them
    * **Space Evenly**: Distributes elements with equal space around them
  </Accordion>

  <Accordion title="Align" icon="align-center">
    Controls the alignment of child elements along the cross axis (perpendicular to the main axis):

    * **Start**: Aligns elements at the start of the cross axis
    * **Center**: Centers elements along the cross axis
    * **End**: Aligns elements at the end of the cross axis
    * **Stretch**: Stretches elements to fill the container along the cross axis
  </Accordion>

  <Accordion title="Wrap" icon="sheet-plastic">
    * **Yes**: Allows elements to wrap onto multiple lines when they exceed the container's width
    * **No**: Forces all elements to remain on a single line, potentially causing overflow
  </Accordion>

  <Accordion title="Gap" icon="arrows-left-right-to-line">
    Sets the spacing between child elements, measured in pixels.
  </Accordion>
</AccordionGroup>

## Hide and disable expressions

Configure dynamic visibility and interaction using JavaScript expressions:

### Available expression types

<Tabs>
  <Tab title="Hide Condition">
    **Purpose**: A JavaScript expression that hides the UI element when it evaluates to a truthy value.

    **Usage**: Control element visibility based on process data or user interactions.

    **Example**: Hide a field based on user role or form state.
  </Tab>

  <Tab title="Disabled Condition">
    **Purpose**: A JavaScript expression that disables the UI element when it returns a truthy value.

    **Usage**: Make elements non-interactive while keeping them visible.

    <Info>
      It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
    </Info>
  </Tab>
</Tabs>

### Expression configuration

Configure expressions for dynamic behavior:

1. Select the UI component in the **UI Designer**
2. Navigate to **Settings** → **your desired platform** → **Overrides (+)** → **Expressions**
3. Configure **Hide** or **Disabled** conditions
4. Add your JavaScript expression

## Best practices for screen configuration

Follow these design principles to create efficient, user-friendly interfaces that perform well across all platforms.

### Core design principles

<AccordionGroup>
  <Accordion title="Single Purpose User Tasks" icon="bullseye">
    **Keep user tasks focused**:

    * Design each user task with **one clear purpose** to avoid cognitive overload
    * Limit the number of UI components per screen to prevent overcrowding
    * Break complex processes into multiple, focused user tasks
    * Use progressive disclosure to reveal information when needed

    <Warning>
      Overcrowded screens with too many UI components can lead to poor user experience and potential performance issues during process execution.
    </Warning>
  </Accordion>

  <Accordion title="Efficient Layout Structure" icon="grid">
    **Optimize container usage**:

    * **Avoid unnecessary nesting** of containers whenever possible
    * **Don't nest containers** solely for sizing or layout purposes
    * **Prefer grid layout** over nested containers for complex arrangements
    * Use **linear layout** and **alignments** for simpler positioning needs

    <Tip>
      Grid layout is your primary tool for creating complex layouts efficiently. It reduces nesting while providing flexible positioning capabilities.
    </Tip>
  </Accordion>

  <Accordion title="Conditional Styling Strategy" icon="eye">
    **Use hide expressions wisely**:

    * **Minimize the use** of hide expressions to maintain performance
    * Consider using **conditional styling** instead of hiding elements when possible
    * Group related conditional elements to reduce expression complexity
    * Document complex conditional logic for maintainability

    <Warning>
      Overusing hide expressions can negatively impact performance and make interfaces harder to maintain.
    </Warning>
  </Accordion>
</AccordionGroup>

### Implementation recommendations

<AccordionGroup>
  <Accordion title="Navigation Design" icon="sitemap">
    **For optimal navigation**:

    * Use **Cards** to guide users through content on single-page forms
    * Apply **Accordions** to collapse validated sections
    * Configure actions properly for wizard-style navigation
    * Consider platform limitations (mobile vs web features)
  </Accordion>

  <Accordion title="Platform Considerations" icon="laptop-mobile">
    **Multi-Platform Design**:

    * Start with generic settings as your base configuration
    * Use platform-specific overrides strategically (e.g., shorter titles on mobile)
    * Test previews across all target platforms
    * Remember that iOS/Android previews are estimates
  </Accordion>

  <Accordion title="Layout Best Practices" icon="table-layout">
    **Effective Layout Strategy**:

    * **Prioritize grid layout** for complex arrangements
    * Use **linear layout** for simple sequential content
    * Apply proper **alignment settings** instead of wrapper containers
    * Choose appropriate layout direction for your content flow
    * Use gap settings to create proper spacing hierarchy
    * Consider responsive wrapping for dynamic content
    * Test layouts with realistic content lengths
  </Accordion>

  <Accordion title="Performance Optimization" icon="bolt">
    **Maintain optimal performance**:

    * Limit UI component density per screen
    * Reduce container nesting depth
    * Minimize complex hide expressions
    * Use efficient layout methods (grid over nested containers)
    * Test with realistic data volumes

    <Check>
      Well-designed screens with proper layout structure and minimal nesting perform better and provide smoother user interactions.
    </Check>
  </Accordion>
</AccordionGroup>

## Configuration examples

### Mobile configuration example

For mobile platforms (iOS & Android), you can configure specific properties:

**Card Component Example**:

* **Screen Title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root)
* **Scrollable Property** (iOS): Define whether the screen should be scrollable (default: true)

### Platform override example

Override a card title for different platforms:

<Tabs>
  <Tab title="Generic Setting">
    **Title**: "Complete Application Process"
  </Tab>

  <Tab title="Mobile Override">
    **Title**: "Complete App" (shorter for mobile displays)
  </Tab>
</Tabs>

This approach ensures your interfaces are optimized for each platform while maintaining consistency in functionality.


# Collection
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/collection/collection

The Collection component functions as a versatile container element, allowing you to iterate through a list of elements and display them according to their specific configurations.

## Configurable properties

* `collectionSource`: This property specifies the process key where a list can be found. It should be a valid array of objects.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_source_key1.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/%20collection_source_key.png)
</Frame>

## Example usage

Here's an example of configuring a Collection component to display a list of products:

<Frame>
  ![Collection configuration for displaying employees](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_example.png)
</Frame>

Source collection data example using an [**MVEL business rule**](../../../actions/business-rule-action/business-rule-action):

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_mvel.png)
</Frame>

```java theme={"system"}
output.put("processData", //this is the key
{
  "products": [ // this is the source that will populate the data on collection
    {
      "name": "Product One Plus",
      "description": "The plus option",
      "type": "normal"
    },
    {
      "name": "Product Two Premium",
      "description": "This is premium product",
      "type": "recommended"
    },
    {
      "name": "Product Basic",
      "description": "The most basic option",
      "type": "normal"
    },
    {
      "name": "Gold Product",
      "description": "The gold option",
      "type": "normal"
    }
  ]
}
);
```

The above configuration will render the Collection as shown below:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/render_collection.gif)

<Info>
  Components within a collection use **relative paths** to the collection source. This means that wherever the collection is found inside the process data, the components inside the collection need their keys configured relative to that collection.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_relative_key.png)

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_key_rule.png)
</Info>

<Warning>
  To send and display dynamic data received on the keys you define to the frontend, make sure to include the following data structure in your root UI element using Message parameters. For instance, if you want to include data for the `processData` key mentioned earlier, your configuration should resemble this:

  ```json theme={"system"}
  {
    "processData": ${processData}
  }
  ```
</Warning>

<Tip>
  **When do you need Collection Prototypes?**

  * **Single layout for all items**: If all items in your collection should display the same way, add one Collection Prototype and leave PIK/PIV empty
  * **Multiple layouts based on item properties**: If items should display differently based on their data (like the `type` field in the example above), add multiple Collection Prototypes with PIK/PIV configured

  For detailed configuration guidance, see the Collection Prototype documentation:
</Tip>

<Card title="Collection prototype" href="/5.9/docs/building-blocks/ui-designer/ui-component-types/collection/collection-prototype" icon="link" />

***

## Forms in collections

<Note>
  Forms in Collections is a feature that enables you to create dynamic, repeatable forms within collection prototypes. This eliminates the need for custom development when building forms with repeatable sections like adding multiple co-debtors or comment entries.
</Note>

### Overview

Forms in Collections addresses common pain points in form design:

* **Dynamic Forms**: No longer need custom development to support dynamic forms that show different form elements based on certain conditions
* **Repeatable Sections**: Create forms with repeatable sections like adding co-debtors, comments, or any list of similar items
* **Flexible Validation**: Support both individual item validation and bulk validation scenarios

The feature allows you to drag Form components directly into Collection Prototypes, where they automatically repeat for each item in your data array.

<Frame>
  ![Forms in Collections](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic1.png)
</Frame>

<Info>
  Collection source rules remain the same as regular collections. Each key in collection prototypes uses a prefix computed from the collection source and the index of the object being displayed. At runtime, keys are constructed with the full object path (e.g., `application.clients[0].name`).
</Info>

### How it works

When you add forms to a collection prototype:

1. **Data Structure**: Your process data contains an array of objects (e.g., `application.clients`)
2. **UI Configuration**: Collection component points to your array, and Form components are placed inside Collection Prototypes
3. **Key Generation**: Form field keys are automatically prefixed with the collection path and item index
4. **Runtime Behavior**: Each collection item gets its own form instance with properly scoped keys

### Implementation guide

<Steps>
  <Step title="Prepare your data structure">
    Set up your process data with an array to hold the repeatable items:

    ```javascript theme={"system"}
    // Define an object named 'application' to store client information
    var application = {
        client: {
            // Store the client's name
            name: "Aang the Last Airbender",
            // Store the loan amount details
            loanAmount: {
                amount: 238989, // The loan amount
                code: "USD" // The currency code for the loan amount
            },
            // List of codebtors associated with the loan
            codebtors: [
                {
                    // First codebtor's name and occupation
                    id: 1,
                    name: "Sokka",
                    occupation: "Boomerang Master"
                },
                {
                    // Second codebtor's name and occupation
                    id: 2,
                    name: "Prince Zuko",
                    occupation: "Firebending Master"
                }
            ]
        }
    };

    // Output the client information from the application object
    output.put("application", { "client": application.client });
    ```
  </Step>

  <Step title="Create the Collection component">
    1. In the UI Designer, add a Collection component
    2. Set the **Collection Source** to point to your array (e.g., `application.client.codebtors`)
    3. The collection will iterate through each item in the array

    <Frame>
      ![Collection configuration for forms](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic2.png)
    </Frame>
  </Step>

  <Step title="Add Collection Prototype with Forms">
    1. Add a **Collection Prototype** as a child of your Collection component
    2. Configure prototype identifier. This is the key that will be used to identify the prototype.
    3. **Drag Form components directly into the Collection Prototype**
    4. Configure form fields with relative keys (e.g., `name`, `email`)

    <Frame>
      ![Collection configuration for forms](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic3.png)
    </Frame>

    <Info>
      This is the key innovation: you can now place Form components directly inside Collection Prototypes, and they will automatically repeat for each collection item.
    </Info>
  </Step>

  <Step title="Configure form fields">
    Configure each form field using relative paths to the collection item data:

    * Use keys like `name`, `email`, `type` (not full paths)
    * The system automatically constructs the full path at runtime
    * Example: `name` becomes `application.client.codebtors[0].name` for the first item

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic4.png)
    </Frame>
  </Step>
</Steps>

### Saving scenarios

Forms in Collections supports two distinct saving approaches, each suited for different use cases:

<Tabs>
  <Tab title="Individual Item Save (Scenario 1)">
    **When to use**: Save one collection item at a time, with validation only for that specific item.

    **Configuration**:

    * Place your Save button **inside the Collection Prototype**
    * Configure a **Collection Item Save Key** on the event handler
    * The edited object will be saved to this key
    * Add a business rule to update the original array and send it back to the frontend

    <Frame>
      ![Collection configuration for forms](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic5.png)
    </Frame>

    **Behavior**:

    * Validates only the forms for the specific collection index where the action is triggered
    * Saves individual items as they are edited
    * Requires business rule to sync changes back to the main array

    <Warning>
      You must configure a business rule to update the original array after individual saves to maintain data consistency.
    </Warning>

    #### Business rule Examples

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic6.png)
    </Frame>

    <AccordionGroup>
      <Accordion title="Business rule  - Add new codebtor in the array">
        ```javascript theme={"system"}
        // This business rule is adapted to the runtime requirements of the FlowX.AI engine.

        // ARGS
        var application = null;
        var client = null;

        if (input["application"] != null) {
            application = input["application"];
        }
        if (application != null && application["client"] != null) {
            client = application["client"];
        }

        // Business Rule Code
        if (client != null) {
            if (!Array.isArray(client["codebtors"])) {
                client["codebtors"] = [];
            }
            var newCodebtor = {"name": ""};
            newCodebtor["id"] = client["codebtors"].length + 1;
            client["codebtors"].push(newCodebtor);
        }

        // OUTPUT
        if (client != null) {
            output["application"] = { "client": client };
        } else {
            output["error"] = {
                "type": "MISSING_FIELD",
                "message": "Client is missing"
            };
        }

        ```
      </Accordion>

      <Accordion title="Send data to the frontend">
        ```javascript theme={"system"}
        { "application": ${application}}
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Bulk Save (Scenario 2)">
    **When to use**: Save all collection items at once with validation for all forms.

    **Configuration**:

    * Place your Save button **outside the Collection** (not in the prototype)
    * Configure a **Custom Key** on the event handler to save the entire array
    * All forms in the collection will be validated simultaneously

    **Behavior**:

    * Validates all forms across all collection prototype items
    * Saves the entire modified array in one operation
    * No additional business rules needed for array synchronization

    ```javascript theme={"system"}
    // Bulk save configuration  
    {
      "customKey": "updatedClients",
      "formsToSubmit": ["clientForm"]
    }
    ```

    <Check>
      Bulk save is simpler to implement as it doesn't require additional business rules to maintain array consistency.
    </Check>
  </Tab>
</Tabs>

Demo:

<video />

### Key formation and validation

Understanding how keys work in Forms in Collections is crucial for proper configuration:

#### Runtime key construction

Keys are automatically constructed using the full object path:

<CodeGroup>
  ```javascript Original Key theme={"system"}
  // In your form field configuration
  "name"
  ```

  ```javascript Runtime Key   theme={"system"}
  // What the system generates at runtime
  "application.clients[0].name"  // For first item
  "application.clients[1].name"  // For second item
  ```
</CodeGroup>

#### Validation behavior

<AccordionGroup>
  <Accordion title="Individual Save Validation">
    When using **Scenario 1** (action inside prototype):

    * Only validates forms for the specific collection index
    * Example: If action is triggered on item 2, only `clients[1]` forms are validated
    * Other items in the collection are ignored during validation
  </Accordion>

  <Accordion title="Bulk Save Validation">
    When using **Scenario 2** (action outside collection):

    * Validates all forms across all collection items
    * All items must pass validation for the save to succeed
    * Comprehensive validation ensures data integrity across the entire collection
  </Accordion>
</AccordionGroup>

### Configuration examples

#### Individual save example

```javascript Event handler configuration theme={"system"}
{
  "event": "CLICK",
  "actionType": "SAVE_DATA", 
  "nodeActionName": "saveClient",
  "collectionItemSaveKey": "currentClient",
  "formsToSubmit": ["clientDetailsForm"],
  "excludeKeys": ["temporaryData"]
}
```

#### Bulk save example

```javascript Event handler configuration theme={"system"}
{
  "event": "CLICK",
  "actionType": "SAVE_DATA",
  "nodeActionName": "saveAllClients", 
  "customKeys": ["allClients"],
  "formsToSubmit": ["clientDetailsForm"]
}
```

### Troubleshooting

<AccordionGroup>
  <Accordion title="Forms not validating correctly">
    **Symptoms**: Validation errors not showing or validation not working as expected

    **Solutions**:

    * Ensure `formsToSubmit` includes the correct form identifiers
    * Check that form fields have proper relative keys configured
    * Verify the event handler is placed in the correct location (inside or outside prototype)
    * For individual saves, confirm the Collection Item Save Key is configured
  </Accordion>

  <Accordion title="Data not saving properly">
    **Symptoms**: Form data not persisting or appearing in wrong location

    **Solutions**:

    * For individual saves: Ensure business rule updates the original array
    * For bulk saves: Verify Custom Key configuration captures the full array
    * Check key formation by examining the process data structure
    * Confirm the Collection Source points to the correct array
  </Accordion>

  <Accordion title="Can't hide form elements based on external variables">
    **Limitation**: Form elements within collections cannot be hidden based on variables outside the collection

    **Workaround**: Use keys from within the collection item object for conditional display. The mechanics of collections require using data from within the current collection item scope.
  </Accordion>
</AccordionGroup>

### Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I hide form elements based on variables outside the collection?">
    No, the mechanics of collections require using keys from within the collection item object. You cannot use variables outside the collection scope to control form element visibility within the collection.
  </Accordion>

  <Accordion title="What happens to null values in form fields?">
    You can configure **Exclude Keys** in the event handler to handle null values. This prevents null or empty values from being included in the saved data.
  </Accordion>

  <Accordion title="How are keys formed at runtime?">
    Keys are constructed with the full object path including array indices. For example, a field with key `name` becomes `application.clients[0].name` for the first collection item.
  </Accordion>

  <Accordion title="Do I need business rules for both saving scenarios?">
    * **Individual Save (Scenario 1)**: Yes, you need a business rule to update the original array
    * **Bulk Save (Scenario 2)**: No, the entire array is saved directly without additional business rules
  </Accordion>
</AccordionGroup>

### Best practices

<CardGroup>
  <Card title="Choose the Right Scenario" icon="route">
    Use Individual Save for real-time editing where users work on one item at a time. Use Bulk Save for form-completion workflows where all data is submitted together.
  </Card>

  <Card title="Key Management" icon="key">
    Use descriptive, relative keys in your form fields. Let the system handle path construction automatically for better maintainability.
  </Card>

  <Card title="Validation Strategy" icon="shield-check">
    Plan your validation approach early. Individual saves validate per item, bulk saves validate everything - choose based on your user experience goals.
  </Card>

  <Card title="Data Structure" icon="database">
    Design your array structure to include all necessary fields from the start. Adding fields later may require updates to existing prototypes.
  </Card>
</CardGroup>

This feature significantly simplifies building dynamic forms with repeatable sections, eliminating the need for custom development while providing flexible validation and saving options.

***

## Common patterns

### Delete an item from a collection

Collections do not have a built-in delete mechanism. To remove an item, use a business rule triggered from within the collection prototype.

<Steps>
  <Step title="Add a delete button inside the Collection Prototype">
    Place a button inside your Collection Prototype. Add an event handler with:

    * **Event:** `CLICK`
    * **Action Type:** `ACTION`
    * **Node Action Name:** your delete business rule
    * **Collection Item Save Key:** a temporary key (e.g., `itemToDelete`) — this saves the clicked item's data so the business rule knows which item to remove
  </Step>

  <Step title="Create the delete business rule">
    Add a **manual, optional, repeatable** business rule on the User Task node.

    **Delete by matching an attribute** (when items have no unique ID):

    ```javascript theme={"system"}
    var clients = input.application.clients || [];
    var itemToDelete = input.itemToDelete;

    if (itemToDelete != null) {
        for (var i = 0; i < clients.length; i++) {
            if (clients[i].name === itemToDelete.name 
                && clients[i].email === itemToDelete.email) {
                clients.splice(i, 1);
                break;
            }
        }
    }

    output.application = { "clients": clients };
    ```

    **Delete by ID** (when items have a unique identifier):

    ```javascript theme={"system"}
    var clients = input.application.clients || [];
    var itemToDelete = input.itemToDelete;

    var updated = clients.filter(function(item) {
        return item.id !== itemToDelete.id;
    });

    output.application = { "clients": updated };
    ```
  </Step>

  <Step title="Send the updated array back to the UI">
    Add a **Send Data to User Interface** action to push the modified array back:

    ```json theme={"system"}
    {
      "application": ${application}
    }
    ```
  </Step>
</Steps>

<Warning>
  Always send the updated array back to the frontend after deletion. Without this step, the UI will still display the deleted item until the next page refresh.
</Warning>

***

### Add an item to a collection dynamically

To let users add new entries to a collection (e.g., an "Add" button), create a business rule that appends a new object to the source array.

```javascript theme={"system"}
var clients = input.application.clients || [];

var newClient = {
    "id": clients.length + 1,
    "name": "",
    "email": ""
};

clients.push(newClient);

output.application = { "clients": clients };
```

Place the "Add" button **outside** the collection, and attach an event handler (type `ACTION`) pointing to this business rule. Then send the data back to the UI with a **Send Data to User Interface** action.

***

### Filter a collection using form controls

Collections do not have built-in filtering. To filter displayed items based on form selections, use the same pattern as [Table cross-component filtering](../table#filter-table-data-using-form-controls):

1. Keep the **original data** in one key (e.g., `application.clients`)
2. Store the **displayed data** in a separate key (e.g., `displayed.clients`)
3. Point the Collection's **Source** to the displayed key
4. On each filter dropdown's `CHANGE` event, trigger a business rule that filters the original data and writes the result to the displayed key

```javascript theme={"system"}
var allClients = input.application.clients || [];
var selectedStatus = input.filter.status;

var filtered = allClients.filter(function(item) {
    if (selectedStatus && item.status !== selectedStatus) return false;
    return true;
});

output.displayed = { "clients": filtered };
```

<Tip>
  For simple client-side transformations (no server roundtrip needed), you can also use [Event Handlers](../../event-handlers) with an `onChange` expression instead of a business rule.
</Tip>

***

## Academy courses

<CardGroup>
  <Card title="Collections and Prototypes course" icon="graduation-cap" href="https://academy.flowx.ai/explore/collections-and-prototypes">
    Hands-on course covering collection configuration, service tasks, and business rules with collections
  </Card>

  <Card title="Handle Dynamic Data course" icon="graduation-cap" href="https://academy.flowx.ai/explore/handle-dynamic-data-flowxai">
    Learn to configure dynamic dropdowns and data-driven UI from process data
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**Academy\_DynamicDataHandling**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/bef76285-0c3e-4828-ad54-fffbbfcfbacf/config/50c00416-aa85-4264-a909-775ad75fcc30/processes) project for working examples of dynamic data in collections and dropdowns.
</Tip>


# Collection Prototype
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/collection/collection-prototype

Create dynamic, data-driven interfaces with different layouts based on item properties using collection prototypes.

<Note>
  Collection prototypes allow you to display items within a collection using different layouts based on their properties, creating more dynamic and context-aware user interfaces.
</Note>

## What are collection prototypes?

Collection prototypes are specialized components that define different display formats for items within a single collection. They act as templates that are applied conditionally based on item properties, allowing you to:

* Display collection items with different layouts based on their data properties
* Create visually distinct displays for featured or highlighted items
* Apply specialized formatting for different item types or states
* Integrate custom components for enhanced functionality
* Add interactive features like item selection

<Info>
  Collection prototypes always work as child components within a parent [Collection component](../collection). While a Collection iterates through a data array, Collection Prototypes determine how each individual item should be displayed.
</Info>

## How collection prototypes work

### Core concepts

Collection prototypes use a simple mechanism to determine which layout to apply to each item. The behavior depends on whether you have one or multiple prototypes:

<CardGroup>
  <Card title="Prototype Identifier Key (PIK)" icon="key">
    The data property used to determine which prototype to apply (e.g., `type`, `status`, `priority`)
  </Card>

  <Card title="Prototype Identifier Value (PIV)" icon="tag">
    The specific value that triggers this prototype layout (e.g., `featured`, `active`, `high`)
  </Card>
</CardGroup>

### When to configure PIK and PIV

<Tabs>
  <Tab title="Single prototype">
    **Configuration**: PIK and PIV are **optional** and should **not** be configured

    <Info>
      If you have only one collection prototype, the system will automatically use that prototype for all items in the array, regardless of their properties. In this case, leave both PIK and PIV empty.
    </Info>
  </Tab>

  <Tab title="Multiple prototypes">
    **Configuration**: PIK and PIV are **required** and **both must be completed**

    <Warning>
      When using multiple collection prototypes, both PIK and PIV must be properly configured for each prototype. The configuration is only valid if both fields are completed.
    </Warning>

    When the collection renders, each item is evaluated against all available prototypes. The first prototype whose identifier key and value match the item's data is used to render that item.
  </Tab>
</Tabs>

### Visual examples

<Tabs>
  <Tab title="Single prototype scenario">
    **Use case**: Displaying a list of menu items where all items have the same layout

    ```javascript theme={"system"}
    // Data structure - all items use the same prototype
    [
      {
        "name": "Margherita Pizza",
        "price": 12.99,
        "description": "Classic tomato and mozzarella"
      },
      {
        "name": "Caesar Salad", 
        "price": 8.99,
        "description": "Fresh romaine with parmesan and croutons"
      }
    ]
    ```

    **Configuration**:

    * PIK: *(leave empty)*
    * PIV: *(leave empty)*

    <Info>
      Since all items use the same layout, no prototype identification is needed.
    </Info>
  </Tab>

  <Tab title="Multiple prototypes scenario">
    **Use case**: Restaurant menu with different layouts for main courses vs desserts

    ```javascript theme={"system"}
    // Data structure with type field for prototype identification
    [
      {
        "name": "pizza",
        "type": "main course",
        "price": 15.99,
        "ingredients": ["tomato", "mozzarella", "basil"]
      },
      {
        "name": "cremsnit",
        "type": "dessert", 
        "price": 6.99,
        "sweetness": "medium"
      }
    ]
    ```

    **Configuration for main course prototype**:

    * PIK: `type`
    * PIV: `main course`

    **Configuration for dessert prototype**:

    * PIK: `type`
    * PIV: `dessert`

    <Check>
      Each item's `type` property determines which prototype layout to use.
    </Check>
  </Tab>
</Tabs>

<Frame>
  ![Animated demonstration of collection prototypes rendering different layouts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/render_collection.gif)
</Frame>

<AccordionGroup>
  <Accordion title="Normal product display">
    <Frame>
      ![Example of a normal product prototype layout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype1.png)
    </Frame>
  </Accordion>

  <Accordion title="Recommended product display">
    <Frame>
      ![Example of a recommended product prototype layout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype2.png)
    </Frame>
  </Accordion>
</AccordionGroup>

## Implementation guide

### 1. Prepare your data

Before implementing collection prototypes, you need to prepare the data structure that will determine which prototype applies to each item.

#### Using a service task node

The most common approach is to use a Service Task node with business rules:

<Steps>
  <Step title="Add a Service Task Node">
    In the FlowX.AI Designer, add a **Service Task** node before your User Task node and connect them with a sequence flow.

    <Frame>
      ![Adding a Service Task node to your process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/task_node_array.png)
    </Frame>
  </Step>

  <Step title="Configure the Business Rule">
    Select your Service Task node, go to the **Business Rules** tab, and add a new business rule or edit an existing one.

    <Frame>
      ![Configuring a business rule in a Service Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/prepare_array_of_products.png)
    </Frame>
  </Step>

  <Step title="Write the Data Preparation Code">
    Use JavaScript to create your data structure and assign it to the process context:

    ```javascript theme={"system"}
    // Create the data structure for products
    const products = [
    {
      "name": "Product One Plus",
      "description": "The plus option",
      "type": "normal",  // This property will determine which prototype to use
      "price": 99.99
    },
    {
      "name": "Product Two Premium",
      "description": "This is premium product",
      "type": "recommended",  // This will use a different prototype
      "price": 149.99
    },
    {
      "name": "Product Basic",
      "description": "The most basic option",
      "type": "normal",
      "price": 49.99
    }
    ];

    // Add the products array to the process data
    output.put("products", products);
    ```
  </Step>

  <Step title="Test Your Data">
    Save your configuration, and test your business rule by using the **Test Rule** feature in the business rules editor to make sure the data is correctly added to the process context.

    <Frame>
      ![Verifying business rule output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/test_your_data.png)
    </Frame>
  </Step>
</Steps>

### 2. Create the UI components

Once your data is prepared, you can implement the collection and its prototypes in the UI Designer:

<Steps>
  <Step title="Create a User Task Node">
    In the FlowX.AI Designer, create or select an existing **User Task** node in your process and click the **brush icon** to open the UI Designer.

    <Frame>
      ![Opening the UI Designer from a User Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_user_task_node_for_collection.gif)
    </Frame>
  </Step>

  <Step title="Add a Collection Component">
    Add a **root component** (like a Card or Container) to your node, then add a **Collection** component inside it. Configure the Collection's **source** to point to your data array (e.g., `products`).

    <Frame>
      ![Adding a Collection component in the UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_source.png)
    </Frame>

    <Info>
      The `collectionSource` property specifies the process key where your list can be found. It should be a valid array of objects. For example, if your data is at `processData.products`, you would set the source to `products`.
    </Info>
  </Step>

  <Step title="Add Collection Prototypes">
    <Tabs>
      <Tab title="Single prototype (simple case)">
        For a single prototype that applies to all items:

        1. Click on your Collection component to select it
        2. Add a **Collection Prototype** as a child component
        3. **Leave PIK and PIV empty** - no configuration needed
        4. The prototype will automatically apply to all items in the collection

        <Info>
          This is the most common scenario when all items in your collection should have the same layout.
        </Info>
      </Tab>

      <Tab title="Multiple prototypes (advanced case)">
        For different display types based on item properties:

        1. Click on your Collection component to select it
        2. Add a **Collection Prototype** as a child component
        3. Configure the prototype's settings:
           * **Prototype Identifier Key**: The field to check (e.g., `type`)
           * **Prototype Identifier Value**: The value to match (e.g., `normal`)

        <Frame>
          ![Configuring a Collection Prototype in the UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_source1.png)
        </Frame>

        4. Repeat for each different prototype you need, using different identifier values

        <Warning>
          Both PIK and PIV must be configured for each prototype when using multiple prototypes.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Design Each Prototype's Layout">
    For each prototype, add the UI components that will display your data:

    1. Select a Collection Prototype
    2. Add components like **Text**, **Image**, **Button**, etc.
    3. Configure each component to use relative paths to the collection item data saved in the Data Model:
       * Use text UI element with the key `${name}`
       * Use text UI element with the key `${description}`

    <Frame>
      ![Adding components to a Collection Prototype](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_elements.gif)
    </Frame>

    <Info>
      Components within a collection use **relative paths** to the collection source. This means that wherever the collection is found inside the process data, the components inside the collection need their keys configured relative to that collection.

      <Frame>
        ![Relative path configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_relative_key.png)
      </Frame>
    </Info>
  </Step>
</Steps>

### 3. Add interactivity

To make your collection items interactive, such as allowing users to select an item:

<Steps>
  <Step title="Create a Node Action">
    Add an [Action](../../../actions/actions) to your [User task node](../../../node/user-task-node):

    1. Go back to the process designer
    2. Select your User Task node
    3. Go to the **Actions** tab
    4. Add a new action with:
       * Type: **Manual**
       * Name: (e.g., `selectItem`)

    <Frame>
      ![Configuration screen for node action setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_interactivity.png)
    </Frame>

    **Configuration options:**

    * Set as **Manual** since users trigger it
    * Mark as **Mandatory** if selection is required to proceed
    * Enable **Repeatable** for changeable selections
  </Step>

  <Step title="Configure an event handler">
    Add an event handler to your collection prototype:

    1. Return to the UI Designer
    2. Select the component in your prototype that should trigger the action
    3. In the Settings panel, add an event handler
    4. Add a  **Collection Item Save Key**.
    5. Add a **Custom Key** and make sure it matches the **Collection Item Save Key**.

    <Frame>
      ![Configuration screen for event handler setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_item_save_key.png)
    </Frame>
  </Step>

  <Step title="Test the Interaction">
    Save your changes and test your process to verify that:

    * Different items display with the correct prototype layouts
    * Interactive elements work as expected
    * Selected data is properly saved to your process data

    <AccordionGroup>
      <Accordion title="Before selection">
        <Frame>
          ![Process data state before item selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype_result.png)
        </Frame>
      </Accordion>

      <Accordion title="After selection">
        <Frame>
          ![Process data state after item selection showing selected product data](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype_result_final.png)
        </Frame>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Best practices

### Working with custom components

<Check>
  When integrating custom components into collection prototypes, follow these best practices:
</Check>

1. **Use relative paths for data access**
   * Configure input keys relative to collection items
   * Example: Use `name` instead of `app.clients.name`

2. **Maintain consistent data structures**
   * Ensure required data exists in collection items
   * Follow consistent data patterns across all items

### Data access patterns

<Tabs>
  <Tab title="Outside collections">
    Components use full paths from data root:

    ```jsx theme={"system"}
    // Input keys:
    // app.name
    // app.signatureImageURL

    data: {
        app: {
            name: "John Doe",
            signatureImageURL: "http://example.com/signature1.png"
        }
    }
    ```
  </Tab>

  <Tab title="Inside collections">
    Components use relative paths:

    ```jsx theme={"system"}
    // Input keys:
    // name
    // signatureImageURL

    data: {
        name: "John Doe",
        signatureImageURL: "http://example.com/signature1.png"
    }
    ```
  </Tab>
</Tabs>

### Performance optimization

* Limit the number of items in your collection when possible
* Simplify complex prototype layouts
* Consider pagination for large data sets
* Optimize images and other media within prototypes
* Avoid deeply nested components within prototypes

<Check>
  **Pro tips:**

  * Test your collection prototypes with various data scenarios
  * Verify data flow through the entire selection process
  * Monitor the process data for correct updates
  * Ensure your UI provides clear visual feedback when an item is selected
</Check>

## Troubleshooting

When working with collection prototypes, you might encounter some common issues:

### Common issues and solutions

<AccordionGroup>
  <Accordion title="Prototype not displaying correctly">
    **Symptoms:**

    * Collection items appear with incorrect layouts
    * All items use the same prototype regardless of identifier values
    * Some items don't render at all

    **Solutions:**

    **For single prototype scenarios:**

    * Ensure PIK and PIV fields are **left empty** - they should not be configured
    * If you accidentally configured PIK/PIV for a single prototype, clear both fields

    **For multiple prototype scenarios:**

    * Verify that your **Prototype Identifier Key** exactly matches the property name in your data
    * Ensure the **Prototype Identifier Value** matches the expected values in your data
    * **Both PIK and PIV must be configured** - partial configuration will not work
    * Check for case sensitivity issues in both keys and values
    * Validate your data structure using the process debugger
    * Confirm that the parent Collection component has the correct source path

    <Warning>
      Configuration is only valid when both PIK and PIV are properly completed for multiple prototypes, or both are left empty for single prototypes.
    </Warning>
  </Accordion>

  <Accordion title="Event handlers not working">
    **Symptoms:**

    * Clicking on items doesn't trigger the expected action
    * Selected data isn't saved to the process
    * No visual feedback when items are selected

    **Solutions:**

    * Confirm that the **Collection Item Save Key** matches exactly with the **Data to send** field in your node action
    * Verify that your node action is properly configured as **Manual** and **Repeatable** if needed
    * Check that the event handler is attached to the correct element within the prototype
    * Ensure the node action has the correct permissions and is properly linked
    * Verify that your root UI element includes the necessary Message parameters to pass data
  </Accordion>

  <Accordion title="Data binding issues">
    **Symptoms:**

    * Components inside prototypes show empty or incorrect data
    * Dynamic content doesn't update properly
    * Error messages in the console related to undefined properties

    **Solutions:**

    * Remember that components inside collections must use relative paths (e.g., `name` instead of `app.clients.name`)
    * Verify your data structure matches what the components expect
    * Use the process debugger to inspect the actual data being passed to the collection
    * Check for null or undefined values that might cause rendering issues
    * Ensure your data is properly structured as an array of objects
  </Accordion>
</AccordionGroup>

### Known limitations

<Warning>
  * **Nested collections** (collections inside collection prototypes) may cause performance issues and should be used sparingly
  * **Deep data structures** might require careful handling of relative paths for proper data binding
</Warning>

### Debugging tips

1. **Use process data inspection:**
   * Monitor the process data before and after interactions with collection prototypes
   * Verify that selected items are correctly saved to the expected process data keys

2. **Test with simplified data:**
   * Start with a minimal data set to confirm basic functionality
   * Gradually add complexity to identify where issues might occur

3. **Isolate components:**
   * Test individual UI components outside the collection context
   * Add components to prototypes one by one to identify problematic elements

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use different layouts for mobile and desktop?">
    Yes, you can create platform-specific overrides for your collection prototypes. Configure different layouts, spacing, and styling for Web, iOS, and Android platforms through the platform tabs in the UI Designer.
  </Accordion>

  <Accordion title="How do I handle missing identifier values?">
    If an item doesn't have the specified identifier key or value, it won't match any prototype. Consider adding a default prototype with a common value like "default" and ensure all items have at least this value as a fallback.
  </Accordion>

  <Accordion title="When should I configure PIK and PIV vs leaving them empty?">
    **Leave PIK and PIV empty** when:

    * You have only one collection prototype
    * All items in your collection should use the same layout

    **Configure both PIK and PIV** when:

    * You have multiple collection prototypes
    * Different items should display with different layouts based on their properties
    * Both fields must be completed for the configuration to work

    <Info>
      This logic has been unchanged since 2021 and is a fundamental aspect of how collection prototypes work.
    </Info>
  </Accordion>

  <Accordion title="Can I use expressions in prototype identifier values?">
    No, prototype identifier values must be static strings that exactly match the values in your data. However, you can transform your data before it reaches the collection to achieve dynamic prototype selection.
  </Accordion>

  <Accordion title="Is there a limit to how many prototypes I can define?">
    There's no hard limit on the number of prototypes, but for performance and maintainability reasons, it's recommended to keep the number reasonable (typically under 5-7 different prototypes).
  </Accordion>

  <Accordion title="What's the difference between Collection and Collection Prototype?">
    A **Collection** is a container that iterates through an array of data items, while a **Collection Prototype** defines how each individual item should be displayed based on its properties. You need at least one Collection Prototype inside a Collection, but you can have multiple prototypes to handle different item types or states.
  </Accordion>
</AccordionGroup>

## Code examples

### Different prototype layouts based on item status

This example shows how to display items differently based on their status (active, pending, completed):

<CodeGroup>
  ```java Process Data Setup theme={"system"}
  // Setting up process data with items of different statuses
  output.put("processData", {
    "tasks": [
      {
        "id": "task-001",
        "title": "Review application",
        "description": "Initial review of customer application",
        "status": "active",
        "priority": "high"
      },
      {
        "id": "task-002",
        "title": "Verify documents",
        "description": "Check submitted documentation for completeness",
        "status": "pending",
        "priority": "medium"
      },
      {
        "id": "task-003",
        "title": "Send confirmation",
        "description": "Email confirmation to customer",
        "status": "completed",
        "priority": "low"
      }
    ]
  });
  ```

  ```javascript Collection Configuration theme={"system"}
  // Collection component configuration
  {
    "type": "COLLECTION",
    "settings": {
      "source": "tasks",
      "direction": "vertical"
    },
    "children": [
      // Active task prototype
      {
        "type": "COLLECTION_PROTOTYPE",
        "settings": {
          "prototypeIdentifierKey": "status",
          "prototypeIdentifierValue": "active"
        },
        "children": [
          // Active task UI elements with highlighted styling
        ]
      },
      // Pending task prototype
      {
        "type": "COLLECTION_PROTOTYPE",
        "settings": {
          "prototypeIdentifierKey": "status",
          "prototypeIdentifierValue": "pending"
        },
        "children": [
          // Pending task UI elements with standard styling
        ]
      },
      // Completed task prototype
      {
        "type": "COLLECTION_PROTOTYPE",
        "settings": {
          "prototypeIdentifierKey": "status",
          "prototypeIdentifierValue": "completed"
        },
        "children": [
          // Completed task UI elements with muted styling
        ]
      }
    ]
  }
  ```
</CodeGroup>

### Multiple identifier keys for complex conditions

You can use multiple collection prototypes with different identifier keys to handle complex display logic:

<CodeGroup>
  ```java Process Data with Multiple Attributes theme={"system"}
  // Setting up process data with items having multiple attributes
  output.put("processData", {
    "notifications": [
      {
        "id": "notif-001",
        "message": "Your application has been approved",
        "type": "success",
        "priority": "high",
        "read": false
      },
      {
        "id": "notif-002",
        "message": "Please review updated terms",
        "type": "info",
        "priority": "low",
        "read": true
      },
      {
        "id": "notif-003",
        "message": "Action required: Missing information",
        "type": "warning",
        "priority": "high",
        "read": false
      }
    ]
  });
  ```

  ```javascript Multiple Prototype Configuration theme={"system"}
  // Collection with multiple prototype conditions
  {
    "type": "COLLECTION",
    "settings": {
      "source": "notifications",
      "direction": "vertical"
    },
    "children": [
      // High priority unread success notification
      {
        "type": "COLLECTION_PROTOTYPE",
        "settings": {
          "prototypeIdentifierKey": "type",
          "prototypeIdentifierValue": "success",
          "additionalConditions": [
            {
              "key": "priority",
              "value": "high"
            },
            {
              "key": "read",
              "value": false
            }
          ]
        },
        "children": [
          // UI elements for high priority unread success notifications
        ]
      },
      // Other prototypes for different combinations...
    ]
  }
  ```
</CodeGroup>

### Nested data structures

Working with nested data in collection prototypes:

<CodeGroup>
  ```java Nested Data Structure theme={"system"}
  // Setting up process data with nested objects
  output.put("processData", {
    "orders": [
      {
        "id": "order-001",
        "customer": {
          "name": "John Smith",
          "tier": "premium"
        },
        "items": [
          { "name": "Product A", "quantity": 2 },
          { "name": "Product B", "quantity": 1 }
        ],
        "status": "processing"
      },
      {
        "id": "order-002",
        "customer": {
          "name": "Jane Doe",
          "tier": "standard"
        },
        "items": [
          { "name": "Product C", "quantity": 3 }
        ],
        "status": "shipped"
      }
    ]
  });
  ```

  ```javascript Accessing Nested Data theme={"system"}
  // Collection prototype accessing nested data
  {
    "type": "COLLECTION",
    "settings": {
      "source": "orders",
      "direction": "vertical"
    },
    "children": [
      // Premium customer prototype
      {
        "type": "COLLECTION_PROTOTYPE",
        "settings": {
          "prototypeIdentifierKey": "customer.tier",
          "prototypeIdentifierValue": "premium"
        },
        "children": [
          // UI elements for premium customers
          {
            "type": "TEXT",
            "settings": {
              "text": "Premium Customer",
              "style": "heading"
            }
          },
          {
            "type": "TEXT",
            "settings": {
              "text": "${customer.name}",
              "style": "subheading"
            }
          },
          // Collection for order items
          {
            "type": "COLLECTION",
            "settings": {
              "source": "items",
              "direction": "horizontal"
            },
            "children": [
              // Item prototype
              {
                "type": "COLLECTION_PROTOTYPE",
                "settings": {},
                "children": [
                  {
                    "type": "TEXT",
                    "settings": {
                      "text": "${name} (${quantity})",
                      "style": "body"
                    }
                  }
                ]
              }
            ]
          }
        ]
      },
      // Standard customer prototype
      {
        "type": "COLLECTION_PROTOTYPE",
        "settings": {
          "prototypeIdentifierKey": "customer.tier",
          "prototypeIdentifierValue": "standard"
        },
        "children": [
          // UI elements for standard customers
        ]
      }
    ]
  }
  ```
</CodeGroup>

## Related components

<CardGroup>
  <Card title="Collection Component" icon="layer-group" href="../collection">
    The parent component that iterates through data arrays and contains Collection Prototypes
  </Card>

  <Card title="Event Handlers" icon="bolt" href="../../event-handlers">
    Add interactivity to Collection Prototypes — run actions on click, or use Run Local Script to update local data when an item is clicked
  </Card>
</CardGroup>


# Checkbox
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/checkbox-form-field

A checkbox form field is an interactive element in a web form that provides users with multiple selectable options. It allows you to choose one or more options from a pre-determined set by checking the corresponding checkboxes.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_new.png)
</Frame>

This type of form field can be used to gather information such as interests, preferences, or approvals, and it provides a simple and intuitive way for users to interact with a form.

## Configuring the Checkbox element

### Checkbox generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Checkbox styling**](#checkbox-styling)

#### Process data key

Process data key establishes the binding between the checkbox element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

#### Properties

* **Label**: The visible label for the checkbox.
* **Helpertext**: Additional information about the checkbox element, which can be optionally hidden within an infopoint.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_props.png)
</Frame>

#### Datasource configuration

* **Default value**: The default value of the checkbox.
* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option** : Define label and value pairs here.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_datasource.png)
</Frame>

#### Validators

The following validators can be added to a checkbox: `required` and `custom`. For more information, see the [validators documentation](../../validators).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_validators.png)
</Frame>

#### Hide/disable expressions

The checkbox behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the checkbox element when it evaluates to the specified result.
* **Disabled condition**: A JavaScript expression that disables the checkbox when it returns a truthy value.

These expressions can be used with any form element. See the following example for details:

<Card title="Input hide/disabled example" href="./input-form-field#hidedisable-expressions" />

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

#### Event handlers

Event handlers can be added to the checkbox element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

<Info>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Info>

### Checkbox settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the checkbox label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Checkbox styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Properties">
        * **Type**: Set the type of the checkbox. Possible values:

          * bordered
          * clear
      </Tab>

      <Tab title="Sizing">
        Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

        * **fill**: Fills the available space.
        * **fixed**: Maintains a fixed width.
        * **auto**: Adjusts the width automatically based on content.
      </Tab>

      <Tab title="Layout">
        * **Direction**: Determines the orientation of the layout, which can be either horizontal or vertical.
        * **Gap**: Specifies the size of the space between rows and columns.
        * **Columns**: Indicates the number of columns in the layout.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, for mobile applications, there's an additional sizing style property specific to select elements:

    * **Height** (pt - points): Determines the vertical size of the select element on the screen.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, for mobile applications, there's an additional sizing style property specific to select elements:

    * **Height** (dp - density-independent pixels): Determines the vertical size of the select element on the screen.
  </Tab>
</Tabs>

#### Checkbox style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)
</Frame>

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width  **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_common.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color  **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Unselected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)
    </Frame>
  </Accordion>

  <Accordion title="Selected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled Unselected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled Selected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover Unselected State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_unselected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover Selected State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_selected_state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>


# Input field
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field

Enable users to input and validate various types of data with flexible configuration options and platform-specific customization.

An input field is a versatile form element that enables users to enter data with built-in validation, conditional visibility, and cross-platform compatibility. Input fields can be customized for different data types and use cases, from simple text entry to specialized formats like email addresses and code snippets.

<Frame>
  ![Input field demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_element.png)
</Frame>

## Configuration overview

Configure your input field using these main sections:

<CardGroup>
  <Card title="Basic Settings" icon="gear">
    Process data binding, labels, and input types
  </Card>

  <Card title="Data & Validation" icon="database">
    Default values, validators, and data formatting
  </Card>

  <Card title="Behavior" icon="bolt">
    Hide/disable conditions and event handlers
  </Card>

  <Card title="Styling" icon="palette">
    Visual appearance and platform-specific overrides
  </Card>
</CardGroup>

## Basic configuration

### Process data key

The process data key establishes the binding between the input element and process data, enabling its later use in:

* [Decision nodes](../../../node/exclusive-gateway-node)
* [Business rule actions](../../../actions/business-rule-action/business-rule-action)
* [Integration tasks](../../../node/message-send-received-task-node#from-integration)

### Core properties

<AccordionGroup>
  <Accordion title="Label" icon="tag">
    **Purpose**: The visible text displayed above or alongside the input field

    **Features**:

    * Supports full Markdown syntax for rich formatting
    * Can include links, emphasis, and other Markdown elements
    * Responsive across all platforms

    <Tip>
      Use Markdown to enhance your labels with **bold**, *italic*, or [linked text](https://www.markdownguide.org/cheat-sheet/).
    </Tip>

    <Frame>
      ![Label with Markdown formatting](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/label_attributed.png)
    </Frame>
  </Accordion>

  <Accordion title="Input Types" icon="keyboard">
    Choose the appropriate input type for your data:

    | Type         | Description          | Validation Features       | Best Used For                                            |
    | ------------ | -------------------- | ------------------------- | -------------------------------------------------------- |
    | **Text**     | General text input   | Length, pattern matching  | Names, titles, descriptions                              |
    | **Number**   | Numeric values only  | Min/max values, decimals  | Quantities, prices, scores                               |
    | **Email**    | Email address format | Built-in email validation | Contact information                                      |
    | **Password** | Masked text input    | Strength requirements     | Authentication, security                                 |
    | **Code**     | Digits-only input    | Only digits allowed       | OTP codes, PIN numbers, postal codes, verification codes |

    <Info>
      The **Code** input type accepts only digit characters during input and stores the value as a **string** (not as a number). This is ideal for numeric codes that should be treated as text, such as OTP codes, PIN numbers, postal codes, or verification codes where leading zeros or string formatting is important.
    </Info>

    <Tip>
      Use **Code** instead of **Number** when you need numeric-only input but want to preserve the value as a string in your data model. This is particularly useful for cases where:

      * Leading zeros must be preserved (e.g., "001234")
      * The value is an identifier rather than a mathematical number
      * You need string operations on numeric values
    </Tip>

    **Code Type Technical Details**:

    * **Input behavior**: Only allows digits (0-9) to be typed
    * **Data storage**: Saves the value as a string data type
    * **Data model support**: String data model types only
    * **Value formatting**: No automatic formatting is applied to the displayed value
    * **Common use cases**: OTP validation, PIN entry, postal codes, verification codes

    ```json theme={"system"}
    {
      "inputType": "code",
      "label": "Enter verification code",
      "placeholder": "000000"
    }
    ```
  </Accordion>

  <Accordion title="Placeholder Text" icon="text">
    **Purpose**: Provide hints or examples of expected input

    **Best Practices**:

    * Keep it concise and helpful
    * Show format examples (e.g., "[john@example.com](mailto:john@example.com)")
    * Avoid using placeholder as primary label
    * Consider accessibility for screen readers
  </Accordion>

  <Accordion title="Prefix & Suffix" icon="paragraph">
    **Prefix**: Text or symbols appearing before the input

    * Currency symbols (\$, €, £)
    * Protocol indicators (https\://, @)
    * Unit prefixes

    **Suffix**: Text or symbols appearing after the input

    * Units of measurement (kg, cm, %)
    * Domain extensions (.com, .org)
    * Contextual indicators

    **Examples**:

    ```
    $ [input field] USD    // Prefix: $, Suffix: USD
    @ [input field]        // Prefix: @
    [input field] %        // Suffix: %
    ```
  </Accordion>

  <Accordion title="Additional Features" icon="plus">
    **Has Clear**: Adds an ✕ button to quickly clear the input content

    * Improves user experience on mobile devices
    * Useful for search fields and optional inputs

    **Helper Text**: Additional context or instructions

    * Can be displayed as regular text below the field
    * Can be hidden within an expandable info point
    * Supports Markdown formatting

    **Update on Blur**: Controls when data is saved

    * Triggers validation when user leaves the field
    * Optimizes performance by reducing frequent updates
  </Accordion>
</AccordionGroup>

## Data configuration

### Datasource configuration

Configure the data source and default values for your input field:

**Default Value**: Set the initial value when the field is first displayed

* Static values for consistent defaults
* Dynamic values from process data
* Calculated values from expressions

<Frame>
  ![Default value](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_datasource1_new.png)
</Frame>

<Warning>
  Consider the user experience impact of default values - they should help users rather than create confusion.
</Warning>

### Validation rules

Ensure data quality with comprehensive validation options:

<Tabs>
  <Tab title="Basic Validators">
    | Validator      | Purpose                    | Configuration               |
    | -------------- | -------------------------- | --------------------------- |
    | **Required**   | Ensures field is not empty | Error message customization |
    | **Min Length** | Minimum character count    | Specify minimum number      |
    | **Max Length** | Maximum character count    | Specify maximum number      |
    | **Email**      | Valid email format         | Works with email input type |
    | **Pattern**    | Custom regex validation    | Define regex pattern        |
  </Tab>

  <Tab title="Numeric Validators">
    | Validator          | Purpose                   | Use Case                |
    | ------------------ | ------------------------- | ----------------------- |
    | **Min Value**      | Minimum numeric value     | Age limits, prices      |
    | **Max Value**      | Maximum numeric value     | Quantity limits, scores |
    | **Decimal Places** | Control decimal precision | Currency, measurements  |
  </Tab>

  <Tab title="Date Validators">
    | Validator       | Purpose                    | Application                    |
    | --------------- | -------------------------- | ------------------------------ |
    | **Past Date**   | Date must be in the past   | Birth dates, historical events |
    | **Future Date** | Date must be in the future | Appointments, deadlines        |
    | **Date Range**  | Within specific date range | Event scheduling, availability |
  </Tab>

  <Tab title="Custom Validators">
    **Purpose**: Complex business logic validation

    **Implementation**: Write custom JavaScript validation functions

    **Examples**:

    * Cross-field validation
    * External API validation
    * Business rule enforcement

    **Documentation**: [Learn more about custom validators](../../validators)
  </Tab>
</Tabs>

<Frame>
  ![Validation example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Input_validat.gif)
</Frame>

## Behavior configuration

### Hide/disable expressions

Define the input field's behavior using JavaScript expressions to control its visibility or disablement:

* **Hide condition**: A JavaScript expression that hides the input field when it evaluates to the specified result.
* **Disabled condition**: A JavaScript expression that disables the input field when it returns a truthy value.

#### Hide expression example

We can use a rule to hide an input field if another field has a null value (it is not filled). For example, the "Mortgage" input field, which remains hidden until users fill in the "Income" field:

<Frame>
  ![Hide expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_hide.png)
</Frame>

**Rule used:**

```javascript theme={"system"}
${application.input.income} === null || ${application.input.income} === ""
```

<Frame>
  ![Hide expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input.income.png)
</Frame>

Result:

<Frame>
  ![Hide expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_hide_result.gif)
</Frame>

#### Disable example

You can use a disabled condition to disable an input element based on values from other fields. When you type 'TEST' in the first input (Name) the second input (Test) will be disabled:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_disabled_condition.png)
</Frame>

**Rule used:**

```javascript theme={"system"}
${application.input.name} === 'TEST'
```

<Frame>
  ![Disabled expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/disabled_input.gif)
</Frame>

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

### Event handlers

Configure interactive behaviors for your input field:

| Event      | Description                  | Common Use Cases                                                |
| ---------- | ---------------------------- | --------------------------------------------------------------- |
| **CHANGE** | Triggered when input changes | Update related fields, trigger calculations, show/hide elements |
| **FOCUS**  | When field receives focus    | Load dynamic data, show helper content                          |
| **BLUR**   | When field loses focus       | Validate input, save data, format display                       |

<Frame>
  ![Event handlers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_ui_actions_new.gif)
</Frame>

**Action Types Available**:

* Navigate to different pages
* Execute business rules
* Call external services
* Update other form elements
* Trigger process actions

<Tip>
  For detailed event handler configuration, see the [Event Handlers guide](../../event-handlers).
</Tip>

## Platform customization

### Settings overrides

Customize your input field differently across platforms:

<Tabs>
  <Tab title="Web Applications">
    **Override Options**:

    * Label text for desktop terminology
    * Placeholder text optimized for keyboard input
    * Helper text with extended descriptions
    * Prefix/suffix for web-specific formatting

    **Web-Specific Features**:

    * Keyboard shortcuts integration
    * Advanced formatting options
    * Enhanced validation messages
  </Tab>

  <Tab title="Mobile Apps">
    **Override Options**:

    * Shorter labels for mobile screens
    * Touch-optimized placeholder text
    * Simplified helper text
    * Mobile-appropriate prefix/suffix

    **Mobile-Specific Features**:

    * Input type optimization for mobile keyboards
    * Touch-friendly clear buttons
    * Platform-specific validation styling
  </Tab>
</Tabs>

<Frame>
  ![Platform override import/export](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Frame>

<Note>
  Override settings can be imported and pushed between platforms, saving configuration time and ensuring consistency.
</Note>

## Visual styling

### Layout options

<Tabs>
  <Tab title="Web Styling">
    <AccordionGroup>
      <Accordion title="Icon Integration">
        **Left Icon**: Visual cue at the start of the input

        * Search icons for search fields
        * User icons for name fields
        * Lock icons for password fields

        **Right Icon**: Action or status indicator

        * Clear buttons (×)
        * Validation status (✓ or ⚠)
        * Dropdown arrows

        **Icon Configuration**:

        * Select from Media Library
        * Custom icon keys
        * Platform-specific icons
      </Accordion>

      <Accordion title="Responsive Sizing">
        | Option    | Behavior                       | Best For           |
        | --------- | ------------------------------ | ------------------ |
        | **Fill**  | Expands to use available space | Full-width forms   |
        | **Fixed** | Maintains specified width      | Consistent layouts |
        | **Auto**  | Adjusts based on content       | Dynamic forms      |
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="iOS Styling">
    **Platform Adaptations**:

    * iOS-specific input styling
    * Native keyboard integration
    * Apple Design Guidelines compliance
    * iOS-specific validation styling
  </Tab>

  <Tab title="Android Styling">
    **Platform Adaptations**:

    * Material Design principles
    * Android keyboard optimization
    * Platform-specific animations
    * Android validation patterns
  </Tab>
</Tabs>

### Theme customization

Override default styling for complete visual control:

<AccordionGroup>
  <Accordion title="Input Field Styling" icon="keyboard">
    **Border & Background**:

    * Border colors for different states
    * Background color customization
    * Border radius and thickness

    **Text Styling**:

    * Font family and size
    * Text color for different states
    * Placeholder text styling

    **States**:

    * Default, focused, disabled, error states
    * Hover effects for web
    * Touch feedback for mobile
  </Accordion>

  <Accordion title="Label & Helper Styling" icon="font">
    **Label Customization**:

    * Typography controls
    * Color options
    * Positioning and alignment

    **Helper Text**:

    * Font styling
    * Color coordination
    * Tooltip appearance
  </Accordion>

  <Accordion title="Validation Styling" icon="triangle">
    **Error States**:

    * Error message styling
    * Input border color changes
    * Icon integration

    **Success States**:

    * Success indicators
    * Positive feedback styling
    * Completion animations
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup>
  <Card title="Accessibility" icon="universal-access" href="../../../../platform-deep-dive/accessibility">
    * Provide clear, descriptive labels
    * Use appropriate input types for better mobile experience
    * Include helper text for complex fields
    * Set an accessibility label when the input has no visible label

    See the [Accessibility guide](../../../../platform-deep-dive/accessibility) for ARIA auto-binding, keyboard navigation, and screen reader details.
  </Card>

  <Card title="User Experience" icon="user">
    * Choose appropriate input types for the data
    * Provide helpful placeholder text and examples
    * Use validation that guides rather than frustrates
    * Consider progressive disclosure for complex forms
    * Implement auto-save functionality where appropriate
    * Group related inputs logically
  </Card>

  <Card title="Data Management" icon="database">
    * Use meaningful process data keys
    * Plan for data validation early in development
    * Consider data format consistency across platforms
    * Implement proper error handling
    * Document validation rules for maintenance
    * Test with real-world data scenarios
  </Card>
</CardGroup>

## Common use cases

| Scenario          | Input Type     | Validation             | Additional Features         |
| ----------------- | -------------- | ---------------------- | --------------------------- |
| **Contact Form**  | Text, Email    | Required, Email format | Clear buttons, helper text  |
| **Login Form**    | Text, Password | Required, Min length   | Security indicators         |
| **Search Field**  | Text           | Min length             | Auto-complete, clear button |
| **OTP codes**     | Code           | Pattern matching       |                             |
| **Numeric Input** | Number         | Min/max values         | Prefix/suffix for units     |
| **Address Entry** | Text           | Format validation      | Auto-complete integration   |


# Multi select
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select

The Multi Select form field is an element that allows users to choose multiple options from a list of choices. Each option consists of a label, which is displayed in the dropdown menu, and a corresponding value, which is stored upon selection.

<Frame>
  ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
</Frame>

<Info>
  For example, consider a scenario where you have options "Sports" with the value "S", "Music" with the value "M", and "Reading" with the value "R". When a user selects both "Sports" and "Music" in the process instance, the values \["S", "M"] will be stored as an array for the "Multi Select" key.
</Info>

## Configuring the Multi Select element

### Multi Select generic settings

These allow you to customize the generic settings for the Multi Select element:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Multi Select styling**](#multi-select-styling)

#### Process data key

Process data key establishes the binding between the multi select element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

<Note>
  The Multi Select component stores selected values as an array, similar to how a Checkbox works. This differs from the single Select component, which stores only a single value.
</Note>

#### Properties

* **Label**: The visible label for the multi select element.
* **Placeholder**: Text that appears within the multi select element when it is empty.
* **Empty message**: Text displayed for custom type when no results are found.
* **Helpertext**: Additional information about the multi select element, which can be optionally hidden within an infopoint.
* **Show selections**: Controls how selected items are displayed. Available display modes:
  * **Comma separated**: Selected values are displayed as a comma-separated text string within the input field (e.g., "Option 1, Option 2, Option 3")
  * **Chips inside**: Selected values appear as chips/badges inside the input field, allowing individual removal with close buttons
  * **Chips outside**: Selected values are displayed as chips/badges below the input field, keeping the input area clean
* **Max. Options Selectable**: Sets the maximum number of options that can be selected simultaneously.

#### Show selections display modes

The "Show selections" property determines how users see their selected options. Each mode offers different benefits depending on your use case:

<Tabs>
  <Tab title="Comma separated">
    Selected values are displayed as a comma-separated text string within the input field. This mode is space-efficient and works well when you have predictable option lengths.

    **Best for:** Simple lists, short option names, read-only display scenarios

    <Frame>
      ![Multi Select with comma separated display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms1.png)
    </Frame>
  </Tab>

  <Tab title="Chips inside">
    Selected values appear as individual chips/badges inside the input field with close buttons `×` for easy removal. This mode provides clear visual separation and allows users to remove specific selections easily.

    **Best for:** Interactive forms, when individual item removal is important, moderate number of selections

    <Frame>
      ![Multi Select with chips inside display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms2.png)
    </Frame>

    **Features:**

    * Individual close buttons for each selection
    * Clear visual distinction between options
    * Hover effects for better interaction
  </Tab>

  <Tab title="Chips outside">
    Selected values are displayed as chips/badges below the input field, keeping the input area clean and uncluttered. This mode is ideal when you expect many selections or longer option names.

    **Best for:** Forms with many selections, long option names, when input field clarity is important

    <Frame>
      ![Multi Select with chips outside display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms3.png)
    </Frame>

    **Benefits:**

    * Input field remains clean and readable
    * Better accommodation for many selections
    * Improved mobile experience with long lists
  </Tab>
</Tabs>

<Tip>
  **Choosing the right display mode:**

  * Use **comma separated** for simple, read-only scenarios or when space is limited
  * Use **chips inside** for interactive forms where users frequently add/remove items
  * Use **chips outside** for complex forms with many selections or when input field clarity is crucial
</Tip>

#### Datasource configuration

* **Default value**: Autofill the multi select field with these values. You need to specify an array of values from the value/label pairs defined in the Datasource tab.

<Frame>
  ![Multi Select default value configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
</Frame>

* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option**: Define label and static value pairs here.

#### Process Data

When the data source type is set to Process Data, the multi select element will be populated with options from a specific process data key. This approach provides dynamic data loading capabilities, allowing options to be generated, modified, or filtered at runtime through business rules.

#### Configuration steps

* Set Source Type: Select "Process Data" from the Source Type dropdown
* Specify Process Data Key: Enter the key path where your options array is stored (e.g., app.options)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/br_multi.png)
</Frame>

Example of JavaScript business rule that populates the multi select element with the values from the process data key:

```javascript theme={"system"}
options = [
    {
        "label": "option 1",
        "value": "option1",
        "enabled": true
    },
    {
        "label": "option 2",
        "value": "option2",
    },
    {
        "label": "option 3",
        "value": "option3",
        "enabled": false
    },
    {
        "label": "option 4",
        "value": "option4",
        "enabled": false
    },
    {
        "label": "option 5",
        "value": "option5"
    }
];

output.put("app", {"options": options});
```

Now the multi select element will be populated with the values from the `app.options` key:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_data_multiselect.png)
</Frame>

#### Validators

You can add multiple validators to a multi select field. For more details, refer to [**Validators**](../../validators).

Common validators for Multi Select include:

* **Required**: Ensures at least one option is selected
* **Custom**: You can add a custom validator to the multi select element.
* **Custom Expression**: You can add a custom expression to the multi select element.

#### Hide/disable expressions

The multi select field's behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the Multi Select field when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the Multi Select field when it returns a truthy value.

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

#### Event handlers

Event handlers can be added to the multi select element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

<Info>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Info>

### Disabled options

You can control the availability of specific options in Multi Select elements by marking them as disabled. This feature is particularly useful for implementing business logic that restricts certain choices based on user permissions, subscription levels, or contextual conditions.

#### Example

<Note>
  The `enabled` property is used to control the availability of the option.
</Note>

```javascript theme={"system"}
options = [
    {
        "label": "option 1",
        "value": "option1",
        "enabled": true
    },
    {
        "label": "option 2",
        "value": "option2",
        "enabled": false
    },
    {
        "label": "option 3",
        "value": "option3",
        "enabled": true
    },
    {
        "label": "option 4",
        "value": "option4",
        "enabled": false
    },
    {
        "label": "option 5",
        "value": "option5"
    },

    
];

output.put("app", {"options": options});
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/disabled_options.png)
</Frame>

### Multi Select settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

### Web overrides

* Properties:
  * **Label**: Override the multi select label.
  * **Helper**: Override helper text/info point.
  * **Placeholder**: Override the placeholder.
  * **Show selections**: Override the show selections.
* Expressions:
  * **Hide**: Override the hide expression.

### iOS overrides

Same as Web overrides.

### Android overrides

Same as Web overrides.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![Importing and pushing overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Multi Select styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Max Rows">
        * **Max Rows**: Adjust the maximum number of rows of the multi select element.
      </Tab>

      <Tab title="Spacing">
        * **Margin**: Adjust the margin of the multi select element.
        * **Padding**: Adjust the padding of the multi select element.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, for mobile applications, there's an additional sizing style property specific to multi select elements:

    * **Fit Width**: Adjust the fit width of the multi select element:
      * **fill**: Fills the available space.
      * **fixed**: Maintains a fixed width.
      * **auto**: Adjusts the width automatically based on content.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, for mobile applications, there's an additional sizing style property specific to multi select elements:

    * **Fit Width**: Adjust the fit width of the multi select element:
      * **fill**: Fills the available space.
      * **fixed**: Maintains a fixed width.
      * **auto**: Adjusts the width automatically based on content.
  </Tab>
</Tabs>

#### Multi Select style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![Multi Select common properties overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_com_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![Multi Select label overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![Multi Select helper overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![Multi Select error overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Empty State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select empty state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_empty_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Active State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select active state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_active_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Filled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**
    * Selected chip background **\[COLOR]**
    * Selected chip text color **\[COLOR]**
    * Selected chip border color **\[COLOR]**

    <Frame>
      ![Multi Select filled state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_filled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select disabled state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_disabled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Error State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select error state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_error_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![Multi Select hover state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_hover_state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![Importing and pushing overrides for Multi Select](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>

# Example - Income sources selection form

Let's create an example using **enumeration data** to create an income sources selection form where users can select multiple income sources from a predefined list, as part of a loan application process.

To create this kind of process, we need the following elements:

* a [**user task node**](../../../node/user-task-node) (here we have the client forms and here we add the MULTI SELECT elements)

<Frame>
  ![Multi Select user task configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_process.png)
</Frame>

### Creating the enumeration

First, we need to create an enumeration for income sources:

1. Create it on your project or in a library.
2. Click on the breadcrumbs (top-right corner) then click **New enumeration** (the Enumeration Designer will now open).
3. Create an enumeration named \`\` with the following values:
   * **S** - Salary
   * **F** - Freelance
   * **R** - Rents
   * **I** - Investments

<Frame>
  ![Income sources enumeration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_enum_income.png)
</Frame>

<Frame>
  ![Income sources enumeration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enum_multi_select.png)
</Frame>

### Configuring the UI

Follow the next steps to configure the UI needed:

1. Select the **user task node** and click the **brush icon** to open [**UI Designer**](../../ui-designer).
2. Add a [**Card**](../root-components/card) UI element as a [**root component**](../root-components/) (this will group the other elements inside it) with the following properties:

* Generic:
  * **Title** - *Loan Application Form*

3. Inside the **card**, add a [**form element**](./).
4. Inside the **form** add the standard form fields (First Name, Last Name, Date of Birth, Email, Income) and then add a **multi select element** for income sources selection.
5. For the multi select element (Income Sources) set the following properties:
   * **Process data key** - `application.incomeSources`

<Info>
  The attribute `application.incomeSources` is the key on which we added income sources selection. It is an array of strings with the source of enumeration.

  <Frame>
    ![Multi Select income sources configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/incomeSource_attr.png)
  </Frame>
</Info>

* **Label** - Income Sources
* **Placeholder** - Select your income sources...
* **Empty message** - No income sources found
* **Show selections** - Comma Separated
* **Max. Options Selectable** - 4 (reasonable limit for income sources)
* **Source type** - Enumeration
* **Enumeration** - Select `incomeSources` from the dropdown

<Frame>
  ![Multi Select income sources configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/incomeSource_dropdown.png)
</Frame>

8. Test and run the process by clicking **Start process**.

<video />

## Data handling and validation

### Common validation scenarios

<Accordion title="Required income sources validation">
  Ensure at least one income source is selected for loan applications:

  ```javascript theme={"system"}
  // Validator expression
  ${application.incomeSources != null && application.incomeSources.length > 0}
  ```

  **Error message**: "Please select at least one income source to continue with your application."
</Accordion>

<Accordion title="Minimum income diversity validation">
  Require at least 2 different income sources for better loan approval chances:

  ```javascript theme={"system"}
  // Validator expression  
  ${application.incomeSources != null && application.incomeSources.length >= 2}
  ```

  **Error message**: "Please select at least 2 income sources to demonstrate income stability."
</Accordion>

<Accordion title="Maximum income sources validation">
  Limit to maximum 4 income sources to keep the application manageable:

  ```javascript theme={"system"}
  // Validator expression
  ${application.incomeSources == null || application.incomeSources.length <= 4}
  ```

  **Error message**: "Please select no more than 4 primary income sources."
</Accordion>

<Accordion title="Primary income validation">
  Ensure that salary or business income is selected as a primary source (for certain loan types):

  ```javascript theme={"system"}
  // Validator expression
  ${application.incomeSources != null && (application.incomeSources.contains("salary") || application.incomeSources.contains("business"))}
  ```

  **Error message**: "At least one primary income source (Salary or Business Income) is required for this loan type."
</Accordion>

## Best practices

<Check>
  **Limit options**: Don't overwhelm users with too many options. Consider grouping or categorizing if you have many choices.
</Check>

<Check>
  **Set maximum selections**: Use the "Max. Options Selectable" property to prevent users from selecting too many options.
</Check>

<Check>
  **Provide clear labels**: Make option labels descriptive and easy to understand.
</Check>

<Check>
  **Consider mobile experience**: Test how selected items display on mobile devices, especially when many options are selected.
</Check>

<Check>
  **Validate selections**: Always validate that the user's selections meet your business requirements using appropriate validators.
</Check>

<Check>
  **Handle empty states**: Provide clear messaging when no options are available or when search yields no results.
</Check>

## Differences from Single Select

| Feature          | Single Select                       | Multi Select                                  |
| ---------------- | ----------------------------------- | --------------------------------------------- |
| **Selection**    | One option only                     | Multiple options                              |
| **Data Storage** | Single value                        | Array of values                               |
| **Display**      | Selected value                      | Chips, comma-separated, or custom format      |
| **Validation**   | Simple required validation          | Min/max selections, required array validation |
| **Use Cases**    | Country selection, status selection | Skills, categories, tags, interests           |
| **Clear Action** | Clears single selection             | Clears all selections                         |

<Info>
  When migrating from Single Select to Multi Select, remember to update your data model to handle arrays and adjust any business rules or integrations that process the selected values.
</Info>


# Radio
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/radio-form-field

Radio buttons are normally presented in radio groups (a collection of radio buttons describing a set of related options). Only one radio button in a group can be selected at the same time.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/radio_form_field.png)

## Configuring the radio field element

### Radio generic settings

These allow you to customize the generic settings for the Radio element:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Radio styling**](#radio-styling)

#### Process data key

Process data key establishes the binding between the radio element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_process_key.png)
</Frame>

#### Properties

* **Label**: The visible label for the radio element.
* **Helpertext**: Additional information about the radio element, which can be optionally hidden within an infopoint.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_label_info.png)
</Frame>

#### Datasource configuration

* **Default value**: Autoselect an option from the radio element based on this value. You need to specify the value from the value/label pairs defined in the Datasource tab.
* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option**: Define label and value pairs here.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_datasource.png)
</Frame>

#### Validators

The following validators can be added to a radio: `required` and `custom`. For more information, see the [validators documentation](../../validators).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_validators.png)
</Frame>

#### Hide/disable expressions

The radio's element behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the Radio element when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the Radio element when it returns a truthy value.

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/radio_validators.png)

#### Event handlers

Event handlers can be added to the radio element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

<Tip>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Tip>

### Radio settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the radio label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Radio styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Properties">
        * **Type**: Set the type of the radio. Possible values:

          * bordered
          * clear
      </Tab>

      <Tab title="Sizing">
        Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

        * **fill**: Fills the available space.
        * **fixed**: Maintains a fixed width.
        * **auto**: Adjusts the width automatically based on content.
      </Tab>

      <Tab title="Layout">
        * **Direction**: Determines the orientation of the layout, which can be either horizontal or vertical.
        * **Gap**: Specifies the size of the space between rows and columns.
        * **Columns**: Indicates the number of columns in the layout.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, for mobile applications, there's a difference on Gap value:

    * **Gap**: pt - points instead of pixels
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, for mobile applications, there's a difference on Gap value:

    * **Gap**: dp - density-independent pixels
  </Tab>
</Tabs>

#### Radio style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)
</Frame>

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width  **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_common.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color  **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Unselected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)
    </Frame>
  </Accordion>

  <Accordion title="Selected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled Unselected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled Selected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover Unselected State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_unselected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover Selected State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_selected_state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>


# Single Select
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/select-form-field

Enable users to choose from a dropdown list of predefined options with advanced features including search, validation, and selective option disabling.

The Single Select form field allows users to choose from a dropdown list of predefined options. Each option consists of a label (displayed to users) and a corresponding value (stored in the process data). This component supports static data, enumerations, and dynamic process data sources with advanced features like search filtering and conditional option enabling.

<Frame>
  ![Single Select demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/select_form_field.png)
</Frame>

<Info>
  **Example**: Consider a dropdown with "Sports" (value: "S") and "Music" (value: "M"). When a user selects "Sports", the value "S" is stored in the process instance under the Select element's data key.
</Info>

## Configuration overview

Configure your single select component using these main sections:

<CardGroup>
  <Card title="Basic Settings" icon="gear">
    Process data binding, labels, and properties
  </Card>

  <Card title="Data Source" icon="database">
    Static options, enumerations, or dynamic data
  </Card>

  <Card title="Behavior" icon="bolt">
    Hide/disable conditions and event handlers
  </Card>

  <Card title="Styling" icon="palette">
    Visual appearance and platform overrides
  </Card>
</CardGroup>

## Basic configuration

### Process data key

The process data key establishes the binding between the select element and process data, enabling its later use in:

* [Decision nodes](../../../node/exclusive-gateway-node)
* [Business rule actions](../../../actions/business-rule-action/business-rule-action)
* [Integration tasks](../../../node/message-send-received-task-node#from-integration)

### Core Properties

<AccordionGroup>
  <Accordion title="Label & Display" icon="tag">
    **Label**: The visible text displayed above the select element

    * Supports Markdown syntax for rich formatting
    * Can include links, emphasis, and other formatting
    * Responsive across all platforms

    **Placeholder**: Text shown when no option is selected

    * Provides guidance on what to select
    * Should be clear and actionable
    * Example: "Choose your preferred option..."

    **Empty Message**: Custom text for no results scenarios

    * Displayed when search yields no matches
    * Helpful for dynamic data sources
    * Example: "No matching options found"
  </Accordion>

  <Accordion title="Search & Interaction" icon="magnifying-glass">
    **Search for Options**: Enable filtering functionality

    * Improves usability for long option lists
    * Real-time filtering as users type
    * Case-insensitive search capabilities
    * Particularly useful for large datasets

    **Has Clear**: Add option to clear selection

    * Provides users with reset functionality
    * Useful for optional fields
    * Improves user control and flexibility

    **Helper Text**: Additional context or instructions

    * Can be displayed as regular text
    * Can be hidden within an expandable info point
    * Supports Markdown formatting
  </Accordion>
</AccordionGroup>

## Data source configuration

### Default value setup

Configure the initial selected option:

**Default Value**: Specify which option should be pre-selected

* Must match a value from your data source
* Improves user experience by reducing required interactions
* Consider user context and common selections

<Frame>
  ![Default value configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/default_value_select.gif)
</Frame>

### Source types

Choose the appropriate data source for your select options:

<Tabs>
  <Tab title="Static Options">
    **Purpose**: Fixed list of options defined at design time

    **Configuration**:

    * **Add Option**: Define label/value pairs manually
    * **Label**: User-friendly display text
    * **Value**: Internal identifier stored in process data
    * **Enabled**: Control option availability (see below)

    **Best For**:

    * Fixed categories (Yes/No, Active/Inactive)
    * Configuration options
    * Simple selection lists
  </Tab>

  <Tab title="Enumeration">
    **Purpose**: Predefined lists managed centrally

    **Benefits**:

    * Consistent across multiple forms
    * Centralized maintenance
    * Automatic updates when enumeration changes
    * Version control for option lists

    **Best For**:

    * Shared vocabularies (countries, currencies)
    * Business domains (departments, categories)
    * Standardized classifications
  </Tab>

  <Tab title="Process Data">
    **Purpose**: Dynamic options from process variables

    **Features**:

    * Runtime data population
    * Context-dependent options
    * Integration with external systems
    * **Enhanced Option Control** (NEW)

    **Best For**:

    * User-specific options
    * Data from external APIs
    * Conditional option sets
    * Dynamic business logic

    <Info>
      Process Data sources now support the **enabled** property for individual option control. See the Enhanced Option Control section below.
    </Info>
  </Tab>
</Tabs>

### Enhanced option control

<Warning>
  Individual option enabling/disabling is available for **Process Data** source types only.
</Warning>

When using Process Data, you can control which options are selectable using the `enabled` property:

**How It Works**:

* **`enabled: true`** or **missing**: Option is selectable (default)
* **`enabled: false`**: Option appears but is disabled

**Example**:

```json theme={"system"}
{
  "options": [
    {
      "value": "available", 
      "label": "Available Option",
      "enabled": true
    },
    {
      "value": "disabled",
      "label": "Disabled Option", 
      "enabled": false
    }
  ]
}
```

**Common Use Cases**: Conditional availability based on permissions, progressive disclosure, status indication (e.g., "Out of Stock"), or guided selection flows.

<Info>
  Disabled options support theming for both **disabled unselected** and **disabled selected** states. An option can be both selected and disabled simultaneously.
</Info>

## Validation

Apply validators to ensure data quality and completeness:

**Available Validators**:

* **Required**: Ensures a selection is made
* **Custom**: Complex business logic validation
* **Conditional**: Validation based on other field values

For comprehensive validation options, refer to our [Validators Guide](../../validators).

## Behavior configuration

### Hide/disable expressions

Control the select element's visibility and interaction using JavaScript expressions:

### Event handlers

Configure interactive behaviors for your select element:

| Event      | Description                      | Common Use Cases                                                         |
| ---------- | -------------------------------- | ------------------------------------------------------------------------ |
| **CHANGE** | Triggered when selection changes | Update dependent fields, trigger calculations, show/hide related content |

**Action Types Available**:

* **Process Actions**: Advance workflow based on selection
* **Data Operations**: Update related form fields
* **UI Updates**: Show/hide dependent elements
* **External Calls**: Fetch related data from APIs

<Tip>
  For detailed event handler configuration, see the [Event Handlers guide](../../event-handlers).
</Tip>

## Platform customization

### Settings overrides

Customize your select element differently across platforms:

<Tabs>
  <Tab title="Web Applications">
    **Override Options**:

    * **Label**: Desktop-optimized terminology
    * **Helper**: Extended descriptions with more context
    * **Placeholder**: Detailed guidance text

    **Web-Specific Features**:

    * Enhanced search with keyboard shortcuts
    * Hover states and advanced animations
    * Larger option lists with scrolling
  </Tab>

  <Tab title="Mobile Apps">
    **Override Options**:

    * **Label**: Concise mobile-friendly text
    * **Helper**: Brief, essential information
    * **Placeholder**: Short, clear guidance

    **Mobile Optimizations**:

    * Touch-friendly option sizing
    * Native picker integration
    * Simplified layouts for smaller screens
  </Tab>
</Tabs>

<Frame>
  ![Platform override import/export](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Frame>

<Note>
  Override settings can be imported and pushed between platforms, saving configuration time and ensuring consistency.
</Note>

## Visual styling

### Layout options

<Tabs>
  <Tab title="Web Styling">
    <AccordionGroup>
      <Accordion title="Icon Integration">
        **Left Icon**: Visual cue for the select purpose

        * Category icons (📂, 🏢, 👤)
        * Functional indicators (🔍, ⚙️, 📊)
        * Status symbols (✓, ⚠️, 🔒)

        **Icon Configuration**:

        * **Icon Key**: Select from Media Library
        * Platform-specific optimization
        * Consistent with design system

        <Frame>
          ![Icon configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/input_icons.png)
        </Frame>
      </Accordion>

      <Accordion title="Responsive Sizing">
        | Option    | Behavior                       | Best For           |
        | --------- | ------------------------------ | ------------------ |
        | **Fill**  | Expands to use available space | Full-width forms   |
        | **Fixed** | Maintains specified width      | Consistent layouts |
        | **Auto**  | Adjusts based on content       | Dynamic layouts    |
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="iOS Styling">
    **Platform Adaptations**:

    * Native iOS picker integration
    * Height specification in points (pt)
    * iOS design guideline compliance
    * Optimized for touch interaction

    **Additional Properties**:

    * **Height (pt)**: Vertical size control for mobile optimization
  </Tab>

  <Tab title="Android Styling">
    **Platform Adaptations**:

    * Material Design principles
    * Height specification in density-independent pixels (dp)
    * Android-specific animations
    * Platform-consistent appearance

    **Additional Properties**:

    * **Height (dp)**: Vertical size control optimized for Android displays
  </Tab>
</Tabs>

### Theme customization

Override default styling for complete visual control:

<Frame>
  ![Theme override interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_all.png)
</Frame>

<AccordionGroup>
  <Accordion title="Common Properties" icon="bars">
    **Layout & Structure**:

    * Border radius for rounded corners
    * Border width for outline definition
    * Text style for typography consistency

    <Frame>
      ![Common properties styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_com_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Label Styling" icon="font">
    **Default State**:

    * Text color customization
    * Font family and size options

    **Disabled State**:

    * Dimmed appearance
    * Consistent with disabled styling

    <Frame>
      ![Label styling options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper Text Styling" icon="square-info">
    **Standard Helper**:

    * Text color and font options

    **Tooltip Helper**:

    * Background color customization
    * Icon color options
    * Typography controls

    <Frame>
      ![Helper text styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Interactive States" icon="hand-pointer">
    <Tabs>
      <Tab title="Empty State">
        **When no option is selected**:

        * Border and background colors
        * Icon color customization
        * Placeholder text styling

        <Frame>
          ![Empty state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_empty_state.png)
        </Frame>
      </Tab>

      <Tab title="Active State">
        **When dropdown is open**:

        * Active border highlighting
        * Background color changes
        * Text and icon color adjustments

        <Frame>
          ![Active state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_active_state.png)
        </Frame>
      </Tab>

      <Tab title="Filled State">
        **When option is selected**:

        * Selected option appearance
        * Confirmation visual cues
        * Clear selection indicator

        <Frame>
          ![Filled state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_filled_state.png)
        </Frame>
      </Tab>

      <Tab title="Error & Disabled States">
        **Error State**: Validation failure appearance
        **Disabled State**: Non-interactive appearance
        **Hover State** (Web only): Mouse-over effects

        <Frame>
          ![Error state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ovselect_error_state.png)
        </Frame>
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

<Info>
  **Time-Saving Tip**: Export your styling configuration from one platform and import it to others to maintain consistency without manual reconfiguration.

  <Frame>
    ![Style import/export workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
  </Frame>
</Info>

## Advanced example: Dynamic dropdowns

Create sophisticated dropdown interactions with dependent selections using process data and business rules.

### Scenario overview

Build a customer contract selection system where available contracts depend on the selected customer:

<Frame>
  ![Dynamic dropdowns demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/d_dropdowns.gif)
</Frame>

### Process structure

**Required Elements**:

1. **Task Node**: Populates dropdown data using business rules
2. **User Task Node**: Contains the select elements and form interface

### Implementation steps

<AccordionGroup>
  <Accordion title="Step 1: Process Setup">
    1. Open **FlowX.AI Designer** → **Processes** → **Definitions**
    2. Click **New Process** to open Process Designer
    3. Add the required nodes:
       * Task node (for data preparation)
       * User task node (for user interface)

    <Frame>
      ![Process structure](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/d_dropdowns1.gif)
    </Frame>
  </Accordion>

  <Accordion title="Step 2: Data Preparation">
    **Task Node Configuration**:

    * **Action Type**: Business Rule
    * **Execution**: Automatic, Mandatory
    * **Language**: MVEL (or your preferred scripting language)

    **Sample MVEL Script**:

    ```java theme={"system"}
    output.put("application",
    {
        "client": {
            "identity": [
            {
                "value": "001",
                "label": "Eddard Stark"
            },
            {
                "value": "002", 
                "label": "Sansa Stark"
            },
            {
                "value": "003",
                "label": "Catelyn Stark"
            }
        ]},
        "contracts": {
            "001": [
                {
                    "value": "c001",
                    "label": "Eddard Contract 1"
                },
                {
                    "value": "c007", 
                    "label": "Eddard Contract 2"
                }
            ],
            "003": [
                {
                    "value": "c002",
                    "label": "Catelyn Contract 1"
                },
                {
                    "value": "c003",
                    "label": "Catelyn Contract 2"
                },
                {
                    "value": "c004",
                    "label": "Catelyn Contract 3"
                }
            ],
            "002": [
                {
                    "value": "c005",
                    "label": "Sansa Contract 1"
                }
            ]
        }
    });
    ```

    <Frame>
      ![Business rule configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/d_business_rukle.png)
    </Frame>
  </Accordion>

  <Accordion title="Step 3: User Interface Setup">
    **User Task Node Configuration**:

    * **Action Type**: Save Data
    * **Execution**: Manual, Mandatory
    * **Data to Send**: `application`

    **UI Structure**:

    1. **Card Element** (root component):
       * **Custom UI Payload**: `{"application": ${application}}`
       * **Title**: "Customer Contract"

    2. **Form Element** (container for selects)

    3. **First Select** (Customer Name):
       * **Process Data Key**: `application.client.selectedClient`
       * **Label**: Customer Name
       * **Source Type**: Process Data
       * **Name**: `application.client.identity`

    4. **Second Select** (Contract ID):
       * **Process Data Key**: `application.client.selectedContract`
       * **Label**: Contract ID
       * **Source Type**: Process Data
       * **Name**: `application.contracts`
       * **Parent**: SELECT (first dropdown)

    <Frame>
      ![Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/select_customer.png)
    </Frame>
  </Accordion>

  <Accordion title="Step 4: Testing & Validation">
    **Test Process**:

    1. Click **Start Process** in the designer
    2. Select a customer from the first dropdown
    3. Verify that the second dropdown populates with relevant contracts
    4. Submit the form to validate data storage

    **Expected Behavior**:

    * Customer selection triggers contract list update
    * Only contracts associated with selected customer appear
    * Form submission stores both selected values

    <Frame>
      ![Dynamic example in action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/dynamic_ex.gif)
    </Frame>
  </Accordion>
</AccordionGroup>

### Enhanced dynamic example with disabled options

Extend the previous example to include conditional option disabling:

```json theme={"system"}
{
  "application": {
    "client": {
      "identity": [
        {
          "value": "001",
          "label": "Eddard Stark",
          "enabled": true
        },
        {
          "value": "002",
          "label": "Sansa Stark", 
          "enabled": false  // Disabled due to account status
        },
        {
          "value": "003",
          "label": "Catelyn Stark",
          "enabled": true
        }
      ]
    },
    "contracts": {
      "001": [
        {
          "value": "c001",
          "label": "Eddard Contract 1",
          "enabled": true
        },
        {
          "value": "c007",
          "label": "Eddard Contract 2 (Expired)",
          "enabled": false  // Disabled due to expiration
        }
      ]
    }
  }
}
```

## Best practices

<CardGroup>
  <Card title="Accessibility" icon="universal-access" href="../../../../platform-deep-dive/accessibility">
    * Provide clear, descriptive labels and helper text
    * Ensure sufficient color contrast for all states
    * Set an accessibility label when the select has no visible label

    See the [Accessibility guide](../../../../platform-deep-dive/accessibility) for keyboard navigation, ARIA auto-binding, and screen reader details.
  </Card>

  <Card title="User Experience" icon="user">
    * Keep option lists manageable (under 10 items when possible)
    * Use search functionality for longer lists
    * Provide clear visual feedback for disabled options
    * Consider default selections for common use cases
    * Group related options logically
    * Show loading states for dynamic data
  </Card>

  <Card title="Data Management" icon="database">
    * Use meaningful keys for integration purposes
    * Plan for data validation and error handling
    * Consider performance impact of large option sets
    * Document business rules for option availability
    * Test with realistic data volumes
    * Implement proper error handling for external data sources
  </Card>

  <Card title="Performance" icon="gauge">
    * Cache frequently used option lists
    * Implement lazy loading for large datasets
    * Optimize search algorithms for responsiveness
    * Consider pagination for very large lists
    * Monitor performance with real-world data
    * Test on various devices and network conditions
  </Card>
</CardGroup>

## Common use cases

| Scenario                 | Configuration                  | Features Used                                 |
| ------------------------ | ------------------------------ | --------------------------------------------- |
| **Country Selection**    | Enumeration source             | Search, large option list                     |
| **Department Selection** | Static options with roles      | Conditional enabling based on user role       |
| **Product Categories**   | Process data with availability | Dynamic options, disabled out-of-stock items  |
| **Status Selection**     | Static with validation         | Required validation, status-dependent actions |
| **Dynamic Filtering**    | Dependent dropdowns            | Parent-child relationships, real-time updates |


# Switch
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field

Enable users to toggle between two states with an intuitive switch interface that stores boolean values in your process instances.

A switch component provides users with a simple toggle interface to select between two states (on/off, true/false). When users interact with the switch, the corresponding boolean value is automatically stored in the process instance for use in decisions, business rules, and integrations.

<Frame>
  ![Switch component demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/switch_form_field.gif)
</Frame>

## Configuration overview

Configure your switch component using these main sections:

<CardGroup>
  <Card title="Basic Settings" icon="gear">
    Process data binding, labels, and switch type
  </Card>

  <Card title="Data & Validation" icon="database">
    Default values, datasources, and validators
  </Card>

  <Card title="Behavior" icon="bolt">
    Hide/disable conditions and event handlers
  </Card>

  <Card title="Styling" icon="palette">
    Visual appearance and platform-specific overrides
  </Card>
</CardGroup>

## Basic configuration

### Process data key

The process data key creates a binding between your switch component and the process data, enabling you to reference the switch value in:

* [Decision nodes](../../../node/exclusive-gateway-node)
* [Business rule actions](../../../actions/business-rule-action/business-rule-action)
* [Integration tasks](../../../node/message-send-received-task-node#from-integration)

### Core properties

<AccordionGroup>
  <Accordion title="Label" icon="tag">
    **Purpose**: The visible text displayed alongside the switch

    **Features**:

    * Supports full Markdown syntax for rich formatting
    * Can include links, emphasis, and other Markdown elements
    * Responsive across all platforms

    <Tip>
      Use Markdown to enhance your labels with **bold**, *italic*, or [linked text](https://www.markdownguide.org/cheat-sheet/).
    </Tip>

    <Frame>
      ![Label with Markdown formatting](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/label_attributed.png)
    </Frame>
  </Accordion>

  <Accordion title="Switch Type" icon="toggle-on">
    Choose the visual representation of your switch:

    | Type         | Description                | Best Used For              |
    | ------------ | -------------------------- | -------------------------- |
    | **Toggle**   | Traditional sliding switch | On/off states, preferences |
    | **Checkbox** | Square checkbox interface  | Agreements, confirmations  |
  </Accordion>

  <Accordion title="Helper Text" icon="square-info">
    **Purpose**: Provide additional context or instructions

    **Options**:

    * Display as regular text below the switch
    * Hide within an expandable info point tooltip
    * Support for Markdown formatting
  </Accordion>
</AccordionGroup>

## Data configuration

### Default value

Set the initial state of your switch component:

* **Default**: Switch starts in the "on" position (true)
* **Alternative**: Configure to start in the "off" position (false)

<Warning>
  Choose your default value carefully as it affects user experience and data collection patterns.
</Warning>

### Validation rules

Apply these validators to ensure data quality:

<Tabs>
  <Tab title="Required True">
    **Use case**: Force users to accept terms, confirm agreements

    **Behavior**: Switch must be in the "on" position to pass validation

    **Error message**: Customize the message shown when validation fails
  </Tab>

  <Tab title="Custom Validator">
    **Use case**: Complex business logic validation

    **Implementation**: Write custom JavaScript validation functions

    **Documentation**: [Learn more about custom validators](../../validators)
  </Tab>
</Tabs>

<Frame>
  ![Switch validation configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/switch_details.png)
</Frame>

## Behavior configuration

### Hide/disable expressions

Define the switch element's behavior using JavaScript expressions to control its visibility or disablement:

* Hide condition: A JavaScript expression that hides the Switch element when it returns a truthy value.
* Disabled condition: A JavaScript expression that disables the Switch element when it returns a truthy value.

#### Hide expression example

We can use a rule to hide a switch element if another field has a null value (it is not filled). For example, the "Terms Agreement" switch, which remains hidden until users fill in the "Email" field:
Rule used:

```javascript theme={"system"}
${application.input.email} === null || ${application.input.email} === ""
```

#### Disable expressions

You can use a disabled condition to disable a switch element based on values from other fields or based on permissions.

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

### Event handlers

Configure interactive behaviors for your switch:

| Event      | Description                         | Common Use Cases                                                |
| ---------- | ----------------------------------- | --------------------------------------------------------------- |
| **CHANGE** | Triggered when switch state changes | Update related fields, trigger calculations, send notifications |

**Action Types Available**:

* Navigate to different pages
* Execute business rules
* Call external services
* Update other form elements

<Tip>
  For detailed event handler configuration, see the [Event Handlers guide](../../event-handlers).
</Tip>

## Platform customization

### Settings overrides

Customize your switch differently across platforms:

<Tabs>
  <Tab title="Web Applications">
    * Override labels for web-specific terminology
    * Adjust helper text for desktop users
    * Modify hide/show expressions for web workflows
  </Tab>

  <Tab title="Mobile Apps">
    * Shorter labels for mobile screens
    * Touch-friendly sizing adjustments
    * Platform-specific validation messages
  </Tab>
</Tabs>

<Frame>
  ![Platform override import/export](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Frame>

<Note>
  Override settings can be imported and pushed between platforms, saving configuration time.
</Note>

## Visual styling

### Layout options

<Tabs>
  <Tab title="Web Styling">
    <AccordionGroup>
      <Accordion title="Label Position">
        **Start**: Label appears before the switch (left side)
        **End**: Label appears after the switch (right side)
      </Accordion>

      <Accordion title="Responsive Sizing">
        | Option    | Behavior                       | Best For                  |
        | --------- | ------------------------------ | ------------------------- |
        | **Fill**  | Expands to use available space | Full-width layouts        |
        | **Fixed** | Maintains specified width      | Consistent column layouts |
        | **Auto**  | Adjusts based on content       | Dynamic layouts           |
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="iOS Styling">
    Similar styling options as web with iOS-specific design guidelines applied automatically.
  </Tab>

  <Tab title="Android Styling">
    Follows Material Design principles with Android-specific styling conventions.
  </Tab>
</Tabs>

### Theme customization

Override default styling for complete visual control:

<Frame>
  ![Theme override interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)
</Frame>

<AccordionGroup>
  <Accordion title="Label Styling" icon="font">
    **Default State**:

    * Text color customization
    * Font family and size options

    **Disabled State**:

    * Dimmed text color options
    * Consistent typography

    <Frame>
      ![Label styling options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper Text Styling" icon="square-info">
    **Standard Helper**:

    * Text color and font options

    **Tooltip Helper**:

    * Background color customization
    * Icon color options
    * Typography controls

    <Frame>
      ![Helper text styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error State Styling" icon="exclamation">
    * Error message text color
    * Font styling for error states
    * Consistent error indication

    <Frame>
      ![Error styling options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Switch States" icon="toggle-on">
    <Tabs>
      <Tab title="Unselected (Off)">
        * Border color customization
        * Background color options
        * Switch knob color

        <Frame>
          ![Unselected state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)
        </Frame>
      </Tab>

      <Tab title="Selected (On)">
        * Active border color
        * Active background color
        * Active knob color

        <Frame>
          ![Selected state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)
        </Frame>
      </Tab>

      <Tab title="Disabled States">
        **Disabled Unselected**:

        <Frame>
          ![Disabled unselected styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)
        </Frame>

        **Disabled Selected**:

        <Frame>
          ![Disabled selected styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)
        </Frame>
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

<Info>
  **Time-Saving Tip**: Export your styling configuration from one platform and import it to others to maintain consistency without manual reconfiguration.

  <Frame>
    ![Style import/export workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
  </Frame>
</Info>

## Best practices

<CardGroup>
  <Card title="Accessibility" icon="universal-access" href="../../../../platform-deep-dive/accessibility">
    * Provide clear, descriptive labels
    * Use helper text for complex switches
    * Set an accessibility label when the switch has no visible label

    See the [Accessibility guide](../../../../platform-deep-dive/accessibility) for keyboard navigation and screen reader details.
  </Card>

  <Card title="User Experience" icon="user">
    * Choose appropriate default values
    * Provide immediate visual feedback
    * Use consistent switch types throughout your application
    * Consider the context when placing switches
  </Card>

  <Card title="Data Management" icon="database">
    * Use meaningful process data keys
    * Plan for boolean value usage in business rules
    * Consider validation requirements early
    * Document switch behavior for other developers
  </Card>
</CardGroup>

## Common use cases

| Scenario               | Configuration                   | Notes                     |
| ---------------------- | ------------------------------- | ------------------------- |
| **Terms & Conditions** | Required validator, default off | Forces user interaction   |
| **Feature Toggles**    | No validation, default varies   | User preference setting   |
| **Permissions**        | Conditional display/disable     | Role-based access control |
| **Status Indicators**  | Read-only mode                  | Display-only information  |


# Text area
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/text-area

Capture multi-line input from users for longer responses such as descriptions, comments, or feedback.

<Frame>
  ![Text area](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/text_area41.png)
</Frame>

It is an important tool for creating intuitive and effective conversational interfaces that can collect and process large amounts of user input.

## Configuring the text area element

### Text area generic settings

These settings added in the Generic tab are available and they apply to all platforms including Web, iOS, and Android:

* [**Process data key**](#prcoess-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Text area styling**](#text-area-styling)

#### Prcoess data key

Process data key creates the binding between form element and process data, so it can be later used in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration)

#### Properties

* **Label**: The visible label for the text area element.
* **Placeholder**: Text that appears within the text area when it is empty.
* **Has Clear**: Option to include a content clear mechanism.
* **Helpertext**: Additional information about the text area field (can be hidden inside an infopoint).
* **Update on Blur**: Update behavior triggered when the text area loses focus.

#### Datasource configuration

The default value for the element can be configured here, this will autofill the text field when you will run the process.

#### Validators

You can add multiple validators to a text area field. For more details, refer to [**Validators**](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/text_area_props.png)

#### Hide/disable expressions

The text area's behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression used to hide the text area when it is evaluated to your desired result.
* **Disabled condition**: A JavaScript expression used to disable the text area when it returns a truthy value

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide_text_area.png)
</Frame>

<Info>
  In the example above, we used a rule to hide a text area element if the value of the switch element above is false.
</Info>

#### Hide expression example

We will use the key defined on the switch element to create a JavaScript hide condition to hide the text area element:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide_text_area1.png)
</Frame>

* Rule used:

```javascript theme={"system"}
${application.client.hasHouse} === false
```

* Result:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/text_area_result.gif)
</Frame>

#### Disable example

For example, you can use a disabled condition to disable a text area element based on what values you have on other elements.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/disable_text_area1.png)
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/disable_text_area2.png)
</Frame>

When you choose a specific value on the radio element (Contact via SMS), the text area is disabled based on the disabled condition.

* Rule used:

```javascript theme={"system"}
${application.client.contact} == "prfS"
```

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

#### Event handlers

Event handlers can be added to the text area field to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

<Tip>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Tip>

### Text area settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the text area label.
  * **Helper**: Override helper text/info point.
  * **Placeholder**: Override the placeholder.
* Expressions:
  * **Hide**: Override the hide expression.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Text area styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Sizing">
        #### Fit W (fit width)

        Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

        * **fill**: Fills the available space.
        * **fixed**: Maintains a fixed width.
        * **auto**: Adjusts the width automatically based on content.

        #### H Type (height type)

        * **fixed**: Maintains a fixed height (pixels)
        * **auto**: Adjusts the height automatically based on the content.

        #### Rows

        * **Min Rows**: Sets the minimum number of rows.
        * **Max Rows**: Sets the maximum number of rows.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    * **fixed height**: Measured in dp - density-independent pixels.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    * **fixed height**: Measured in pt - points.
  </Tab>
</Tabs>

#### Text area style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_all.png)
</Frame>

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_common_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color  **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Empty State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_empty_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Active State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_active_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Filled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_filled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_disabled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Error State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_error_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_hover_state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>


# Card
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card

A card in FlowX.AI is a graphical component designed for the purpose of grouping and aligning various elements. It offers added functionality by incorporating an accordion feature, allowing users to expand and collapse content as needed.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/card_ex.gif)
</Frame>

The following properties that can be configured:

## Properties and settings

### Settings (applicable across all platforms)

These settings added in the **Generic** tab are available and they apply to all platforms including Web, iOS, and Android.

#### When used as root

When the Card is utilized as the root component, it offers the following settings:

* **Custom UI Payload**: A valid JSON describing the custom data transmitted to the frontend when the process reaches a specific user task.
* **Title**: The title displayed on the card.
* **Subtitle**: Additional descriptive text accompanying the card.
* **Has accordion**: Introduces a Bootstrap accordion, facilitating the organization of content within collapsible items. It ensures that only one collapsed item is displayed at a time.
* **Default collapse state**: When accordion is enabled, this property determines whether the card is initially collapsed or expanded when first loaded. Options:
  * **Expanded** (default): The card content is visible when the screen loads.
  * **Collapsed**: The card content is hidden when the screen loads, and users must click to expand it.

<Info>
  The accordion feature is not available for mobile configuration.
</Info>

#### Mobile configuration (iOS & Android)

For mobile configuration (iOS and Android), you can also configure the following property (not available on Web configuration):

* **Screen title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root).

<Frame>
  ![Android Screen Title](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/screen_title_android%20%282%29.png)
</Frame>

### Card settings overrides

You may want to override the card title or subtitle set as **Generic** to be displayed differently on mobile devices. For example, on the web, titles might be shorter.

<Tabs>
  <Tab title="Web">
    Available properties overrides for web (overriding properties set in **Generic** settings tab):

    * Title
    * Subtitle

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/overrides_web.png)
    </Frame>
  </Tab>

  <Tab title="Android">
    Available properties overrides for Android (overriding properties set in **Generic** settings tab):

    * Title
    * Subtitle

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/overrides_android.png)
    </Frame>
  </Tab>

  <Tab title="iOS">
    Available properties overrides for iOS (overriding properties set in **Generic** settings tab):

    * Title
    * Subtitle
  </Tab>
</Tabs>

#### When not used as root

When the card is not the root, you can configure: **Title**, **Subtitle**, **Card Style**, **Has Accordion**, and **Default collapse state**.

Use cards in your designs to organize and present content, enhancing the overall user experience.

## Styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Layout">
        When designing for the web, consider the layout options available for the card. These options include:

        * **Direction**: Choose between **Horizontal** or **Vertical** alignment to define the flow of components. For example, select Horizontal for a left-to-right layout.
        * **Justify (H)**: Specify how content is aligned along the main axis. For instance, select end to align items to the end of the card.
        * **Align (V)**: Align components vertically within their card using options such as top, center, or bottom alignment.
        * **Wrap**: Enable wrapping to automatically move items to the next line when they reach the end of the card. Useful for creating multi-line layouts.
        * **Gap**: Define the space between components to control the distance between each item. Adjusting the gap enhances visual clarity and organization.
      </Tab>

      <Tab title="Sizing">
        Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

        * **fill**: Fills the available space.
        * **fixed**: Maintains a fixed width.
        * **auto**: Adjusts the width automatically based on content.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, for mobile applications, there's an additional layout style property specific to cards when used as the root component:

    * **Scrollable**:  This property allows you to define the desired behavior of the screen, specifying whether it should be scrollable or not. By default, this property is set to true, enabling scrolling functionality.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, for mobile applications, there's an additional layout style property specific to cards when used as the root component:

    * **Scrollable**:  This property allows you to define the desired behavior of the screen, specifying whether it should be scrollable or not. By default, this property is set to true, enabling scrolling functionality.
  </Tab>
</Tabs>

### Theme overrides

Customize the appearance by overriding style options coming from your default theme. Available overrides:

* Border width
* Border radius
* Border color
* Background color
* Shadow
* Title
* Title Color
* Subtitle
* Subtitle Color

<Card title="Layout Demos" href="https://tburleson-layouts-demos.firebaseapp.com/#/docs" icon="link" />

## Validating elements

To ensure the validation of all form elements and custom components within a card upon executing a Save Data action such as **Submit** or **Continue**, follow these steps:

1. When adding an event handler to a button inside a card, locate the dropdown menu labeled **Add forms to submit**.
2. From the dropdown menu, select the specific forms, individual form elements, or custom components you wish to validate.
3. If you select custom components, ensure they are properly configured to handle validation and data saving responsibilities.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2013.26.20.png)
</Frame>

***

### Custom component validation

Event handlers enable validation and data management for custom components alongside form elements. This provides flexibility if you want to design custom components for entire screens, such as custom forms not natively supported by the platform.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2013.37.15.png)
</Frame>

#### Key features

* **Validation API**: The renderer provides a public API for validating custom components before triggering an action.
* **Custom Component Responsibilities**:
  * Validate custom forms and return a boolean (`true` for valid, `false` for invalid).
  * Display validation errors in the UI for invalid data.
  * Populate a `saveData` property with the structured data to be submitted.
* **Configurator Responsibilities**:
  * Select custom components in the **Add forms to submit** dropdown when configuring an event handler.
  * Set the custom key to store the data submitted by the custom component.

By including custom components in the validation process, you can now validate and retrieve data from custom form sections, ensuring comprehensive and reliable form submission.


# Container
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/container

A container in FlowX.AI is a versatile building block that empowers you to group components and arrange them as needed, providing flexibility in UI design. It can also serve as the root component for your design.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_ex.gif)

The following properties can be configured in the container:

## Properties and settings

### Settings (applicable across all platforms)

These settings added in the **Generic** tab are available and they apply to all platforms including Web, iOS, and Android.

#### When used as root

When employed as the root component, the container offers the following settings:

* **Custom UI Payload**: A valid JSON describing the data sent to the frontend when the process reaches a specific user task.
* **Expressions (Hide condition)**: JavaScript expressions utilized to dynamically hide components based on conditions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_root_new.png)

#### When not used as root

When the container is not used as the root, you can configure only the **Hide Condition** property.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_not_root.png)

By leveraging containers, you gain the ability to structure your UI elements efficiently, enhancing the overall design and usability of your application.

### Container settings overrides

You may want to override settings configured in the **Generic** tab to be displayed differently on mobile devices.

* **Hide expressions**: Use Overrides in the Settings tab to hide a container on a specific platform.

<Info>
  For instance, you can set a container to appear on all platforms, or create an override to hide it on mobile but show it on web.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/override_hide.gif)
</Info>

To achieve this:

1. Select a Container element in the UI Designer, then navigate to Settings -> your desired platform -> Overrides (+) -> Expressions -> Hide.
2. Add your JavaScript Hide condition.

## Styling

<Tabs>
  <Tab title="Web">
    <Tabs>
      <Tab title="Layout">
        When designing for the web, consider the layout options available for the container. These options include:

        * **Position**
          * **Static**: This style remains fixed and does not scroll along with the page content.
          * **Sticky**: When the sticky property is enabled, the container maintains its position even during scrolling.
            * **Sticky layout**: You have the option to specify minimum distances between the container and its parent element while scrolling. At runtime, sticky containers will keep their position on scroll relative to top/ bottom/ right/ left margin of the parent element.

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Screenshot%202023-12-13%20at%2017.18.39.png)
        </Frame>

        * **Direction**: Choose between **Horizontal** or **Vertical** alignment to define the flow of components. For example, select Horizontal for a left-to-right layout.
        * **Justify (H)**: Specify how content is aligned along the main axis. For instance, select end to align items to the end of the container.
        * **Align (V)**: Align components vertically within their container using options such as top, center, or bottom alignment.
        * **Wrap**: Enable wrapping to automatically move items to the next line when they reach the end of the container. Useful for creating multi-line layouts.
        * **Gap**: Define the space between components to control the distance between each item. Adjusting the gap enhances visual clarity and organization.
      </Tab>

      <Tab title="Sizing">
        Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

        * **fill**: Fills the available space.
        * **fixed**: Maintains a fixed width.
        * **auto**: Adjusts the width automatically based on content.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, there are exceptions, particularly with **Sticky layout**:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_mobile.png)
    </Frame>

    In mobile configurations, the right and left properties for **Sticky layout** are ignored by the iOS renderer.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, there are exceptions, particularly with **Sticky layout**:

    ![Sticky layout on Android](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_mobile.png)

    In mobile configurations, the right and left properties for **Sticky layout** are ignored by the Android renderer.
  </Tab>
</Tabs>

### Theme overrides

Customize the appearance by overriding style options coming from your default theme. Available overrides:

* Border width
* Border radius
* Border color
* Background color
* Shadow

More layout demos available below:

<Card title="Layout Demos" href="https://tburleson-layouts-demos.firebaseapp.com/#/docs" icon="link" />

For more information about styling and layout configuration, check the following section:

<Card title="UI Designer" href="../../ui-designer#styling" />


# Custom component
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/custom

Custom components are 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.

<Warning>
  Starting with **3.4.7** platform version, for User Tasks containing UI Elements, when the page is rendered, the Backend (BE) should, by default, send to the Frontend (FE) all available data as process variables with matching keys.

  If the User Task also includes a **custom component**, the BE should send, in addition to default keys, objects mentioned in the "Message" option of the root element.
</Warning>

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.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom.png)

The properties that can be configured are as follows:

* **Identifier** - This enables the custom component to be displayed within the component hierarchy and determines the actions available for the component.
* **Input keys** - These are used to specify the pathway to the process data that components will utilize to receive their information.
* [**Event Handlers**](../../event-handlers) - actions defined here will be made available to the custom component

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom_settings.png#center)
</Frame>

## Prerequisites (before creation)

* **Angular Knowledge**: You should have a good understanding of Angular, as custom components are created and imported using Angular.

* **Angular CLI**: Ensure that you have Angular CLI installed.

* **Development Environment**: Set up a development environment for Angular development, including Node.js and npm (Node Package Manager).

* **Component Identifier**: You need a unique identifier for your custom component. This identifier is used for referencing the component within the application.

## Creating a custom component (Web)

To create a Custom Component in Angular, follow these steps:

1. Create a new Angular component using the Angular CLI or manually.
2. Implement the necessary HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior of your custom component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_comp.png)

## Importing the component

After creating the Custom Component, you need to import it into your application.

In your `app.module.ts` file (located at src → app → app.module.ts), add the following import statement:

```ts theme={"system"}
`import { YourComponent } from '@app/components/yourComponent.component'`
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/import_cus.gif)

## Declaration in AppModule

In the same `app.module.ts` file, declare your Custom Component within the `declarations` array in the `@NgModule` decorator:

```ts theme={"system"}
@NgModule({
  declarations: [
    // ...other components
    YourComponent
  ],
  // ...other module configurations
})

```

## Declaration in FlxProcessModule

To make your Custom Component available for use in processes created in FlowX.AI Designer, you need to declare it in `FlxProcessModule`.

In your process.module.ts file (located at src > app > modules > process > process.module.ts), add the following import statement:

```ts theme={"system"}
import { YourComponent } from '@app/components/yourComponent.component';
```

Then, declare your Custom Component in the `FlxProcessModule.forRoot` function:

```ts theme={"system"}
FlxProcessModule.forRoot({
  components: {
    // ...other components
    yourComponent: YourComponent
  },
  // ...other module configurations
})
```

## Using the custom component

Once your Custom Component is declared, you can use it for configuration within your application.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_component.gif)

## Data input and actions

The Custom Component accepts input data from processes and can also include actions extracted from a process. These inputs and actions allow you to configure and interact with the component dynamically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_input_data.png)

## Extracting data from processes

There are multiple ways to extract data from processes to use within your Custom Component. You can utilize the data provided by the process or map actions from the BPMN process to Angular actions within your component.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_loader_input.png)
</Frame>

<Warning>
  Make sure that the Angular actions that you declare match the names of the process actions.
</Warning>

## Styling with CSS

To apply CSS classes to UI elements within your Custom Component, you first need to identify the UI element identifiers within your component's HTML structure. Once identified, you can apply defined CSS classes to style these elements as desired.

Example:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/Screenshot%202023-10-10%20at%2012.29.51.png)
</Frame>

## Custom component example

Below you can see an example of a basic custom loader component built with Angular:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/2023-10-10%2012.01.58.gif)

## Additional considerations

* **Naming Conventions**: Be consistent with naming conventions for components, identifiers, and actions. Ensure that Angular actions match the names of process actions as mentioned in the documentation.

* **Component Hierarchy**: Understand how the component fits into the overall component hierarchy of your application. This will help determine where the component is displayed and what actions are available for it.

* **Documentation and Testing**: Document your custom component thoroughly for future reference. Additionally, testing is crucial to ensure that the component behaves as expected in various scenarios.

* **Security**: If your custom component interacts with sensitive data or performs critical actions, consider security measures to protect the application from potential vulnerabilities.

* **Integration with FlowX.AI Designer**: Ensure that your custom component integrates with FlowX.AI Designer, as it is part of the application's process modeling capabilities.

## Creating a custom component (iOS)

Enhance your skills with our academy course! Learn how to develop and integrate a custom iOS component with FlowX.AI:

<Card title="iOS Custom Component" href="https://academy.flowx.ai/module/ios-custom-component" icon="school" />


# Root Components in UI Design
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/root-components

Root components serve as the foundation for structuring user interfaces, providing the framework for arranging and configuring different types of components.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/root_components_new.gif)

Root components play a crucial role in defining the layout and hierarchy of elements within an application. Here's an overview of key root components and their functionalities:

### Container

The Container component is a versatile element used to group and configure the layout for multiple components of any type. It provides a flexible structure for organizing content within a UI.

Learn more about [Container components](./container).

### Card

The Card component functions similarly to a Container component but also offers the capability to function as an accordion, providing additional flexibility in UI design.

Discover more about [Card components](./card).

### Custom

Custom components are Web components developed within the container application and dynamically passed to the SDK at runtime. These components are identified by their unique names and enable developers to extend the functionality of the UI.

Explore [Custom components](./custom) for advanced customization options.

A card or a container can hold a hierarchical component structure as this example:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/root_comp_str.png)
</Frame>

Available children for **Card** and **Container** are:

1. [**Form**](../form-elements/) - Used to group and align form field elements (inputs, radios, checkboxes, etc.).

<Info>
  For more information about the form elements, please refer to the [**Form elements**](../form-elements/) section.
</Info>

2. [**Image**](../image) - Allows you to configure an image in the document.
3. **Text** - A simple text can be configured via this component; basic configuration is available.
4. **Link** - Used to configure a hyperlink that opens in a new tab.
5. [**Button**](../buttons) - Multiple options are available for configuration, with the most important part being the possibility to add actions.
6. [**File Upload**](../buttons) - A specific type of button that allows you to select a file.
7. [**Custom**](./custom) - Custom components.
8. [**Indicators**](../indicators) - Message UI elements to display different types of messages.

Learn more:

<CardGroup>
  <Card title="Card" href="./card" icon="file" />

  <Card title="Container" href="./container" icon="file" />

  <Card title="Custom" href="./custom" icon="file" />
</CardGroup>


# UI Designer
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-designer

The FlowX.AI UI Designer is a comprehensive, multi-platform interface creation tool that enables visual design of user experiences across web, iOS, and Android platforms without extensive coding.

## Purpose

The **FlowX.AI UI Designer** is an intuitive interface creation tool for building user interfaces within FlowX.AI processes. It provides a visual editor where you can add, arrange, and configure UI components to create rich web interfaces for your business processes.

### Key capabilities

<CardGroup>
  <Card title="Multi-Platform Support" icon="desktop">
    Create interfaces with platform-specific configuration and styling across Web, iOS, and Android
  </Card>

  <Card title="Visual Interface Design" icon="paintbrush">
    Use a drag-and-drop environment to design diverse UI templates with various elements and components
  </Card>

  <Card title="Real-Time Preview" icon="eye">
    Preview your designs across different platforms and themes with live feedback
  </Card>

  <Card title="Component Library" icon="layers">
    Access ready-to-use UI components including form elements, containers, and specialized components
  </Card>
</CardGroup>

<Info>
  The UI Designer integrates with BPMN process flows, making it available for [**User Task**](../node/user-task-node) nodes and **Navigation Areas** to create contextual user interfaces.
</Info>

## UI Designer interface

The UI Designer provides a comprehensive interface for creating and configuring user interfaces within your FlowX.AI processes.

### Platform selection

The UI Designer supports multi-platform design with dedicated configuration tabs:

<Tabs>
  <Tab title="Web Platform">
    **Full Feature Support**: Complete UI Designer functionality with all component types and navigation features

    * All UI component types supported
    * Full navigation area capabilities
    * Zones with headers and footers
    * Single page and wizard navigation types
  </Tab>

  <Tab title="iOS Platform">
    **Mobile-Optimized Interface**: Platform-specific properties and limitations

    * Basic navigation areas (no zones with headers/footers)
    * Screen title configuration for navigation bar
    * Scrollable property for card components
    * Platform-specific property overrides
  </Tab>

  <Tab title="Android Platform">
    **Mobile-Optimized Interface**: Android-specific adaptations

    * Basic navigation areas (no zones with headers/footers)
    * Screen title configuration for navigation bar
    * Platform-specific property overrides
    * Material design considerations
  </Tab>
</Tabs>

### Configuration panels

The UI Designer interface consists of configuration sections for comprehensive component setup:

<AccordionGroup>
  <Accordion title="Settings Tab" icon="toolbox">
    **Generic Configuration**: Properties available cross-platform (Web, Android and iOS)

    **Platform-Specific Settings**: Override generic properties for specific platforms

    * Property overrides (Title, Subtitle, Helper text)
    * Expression overrides (Hide conditions)
    * Import/export functionality between platforms
  </Accordion>

  <Accordion title="Styles Tab" icon="palette">
    **Theme Integration**: Components inherit styling from the active theme by default

    **Theme Overrides**: Customize component appearance beyond theme settings

    * Platform-specific styling
    * Conditional styling (for Text, Link, Container elements)
    * Import/export styles between platforms
  </Accordion>

  <Accordion title="Preview" icon="eye">
    **Multi-Platform Preview**: Switch between platforms to preview designs

    * Real-time platform switching
    * Theme selection for preview
    * Visual estimation for mobile platforms

    <Info>
      iOS and Android previews are estimates to help visualize mobile views.
    </Info>
  </Accordion>
</AccordionGroup>

### UI components available

The FlowX.AI platform offers a variety of ready-to-use UI components for creating rich web interfaces:

<AccordionGroup>
  <Accordion title="Root Components" icon="object-group">
    **Layout Foundation Elements**:

    * **[Container](./ui-component-types/root-components/container)**: Flexible grouping and layout control
    * **[Card](./ui-component-types/root-components/card)**: Content cards with built-in styling
    * **[Custom](./ui-component-types/root-components/custom)**: Advanced custom component integration

    These components serve as the foundation for structuring user interfaces and provide the framework for arranging other UI elements.
  </Accordion>

  <Accordion title="Form Elements" icon="clipboard-list">
    **Data Collection Components**: Essential for collecting user information

    * **[Input](./ui-component-types/form-elements/input-form-field)**: Text input fields
    * **[Textarea](./ui-component-types/form-elements/text-area)**: Multi-line text input
    * **[Select](./ui-component-types/form-elements/select-form-field)**: Dropdown menus
    * **[Checkbox](./ui-component-types/form-elements/checkbox-form-field)**: Multiple selection options
    * **[Radio](./ui-component-types/form-elements/radio-form-field)**: Single selection from options
    * **[Switch](./ui-component-types/form-elements/switch-form-field)**: Toggle controls
    * **[Datepicker](./ui-component-types/form-elements/datepicker-form-field)**: Date and time selection
    * **[Slider](./ui-component-types/form-elements/slider)**: Range and numeric input
    * **[Segmented Button](./ui-component-types/form-elements/segmented-button)**: Multi-option selection

    Each form element serves a unique purpose and offers different options for capturing user input.
  </Accordion>

  <Accordion title="Action and Display Elements" icon="location-arrow">
    **Interactive and Display Components**:

    * **[Buttons](./ui-component-types/buttons)**: Action triggers and navigation
    * **[File Upload](./ui-component-types/file-preview)**: Document and media upload
    * **[Image](./ui-component-types/image)**: Media display
    * **[Typography](./ui-component-types/typography)**: Text and links
    * **[Table](./ui-component-types/table)**: Structured data presentation
    * **[Indicators](./ui-component-types/indicators)**: Status and message display
  </Accordion>

  <Accordion title="Collections" icon="layer-group">
    **Dynamic Content Components**:

    * **[Collection](./ui-component-types/collection/collection)**: Dynamic lists of data
    * **[Collection Prototype](./ui-component-types/collection/collection-prototype)**: Templates for collection items

    These components handle repeated content and dynamic data presentation.
  </Accordion>
</AccordionGroup>

### Component configuration

After adding a UI component, the right-side menu displays configuration options:

* **Settings Tab**: Configure component properties and behavior
* **Styles Tab**: Customize appearance and apply theme overrides
* **Platform Overrides**: Adapt components for specific platforms

### Navigation areas integration

Navigation areas can be configured through the UI Designer, providing:

* Hierarchical navigation structure
* Platform-specific navigation capabilities
* Copy/paste functionality for consistency across platforms

## Using the UI designer

To access the UI Designer and start building interfaces:

<Steps>
  <Step title="Open FlowX.AI Designer">
    Navigate to **FlowX.AI Designer** and select **Definitions** from the **Processes** tab.
  </Step>

  <Step title="Select Process">
    Choose a **process** from the process definitions list.
  </Step>

  <Step title="Edit Process">
    Click the **Edit process** button to enter editing mode.
  </Step>

  <Step title="Access UI Designer">
    Select a **User Task node** or a **Navigation Area** then click the **brush icon** to open the **UI Designer**.

    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_ui_designer.gif)
  </Step>
</Steps>

<Info>
  The UI Designer is available for [**User Task**](../node/user-task-node) nodes and **Navigation Areas** elements, providing contextual interface design capabilities.
</Info>

<Tip>
  **Productivity Features**:

  * **Undo/Redo**: Available within the UI Designer for actions such as dragging, dropping, or deleting elements
  * **Keyboard Shortcuts**: Use keyboard commands for quick access to undo/redo functionality
  * **Drag and Drop**: Support for dragging and dropping elements in the preview section
  * **Settings Panel**: Right-side menu displays configuration options after adding components
</Tip>

## Comprehensive design guides

Master the UI Designer with our detailed guides covering every aspect of interface creation:

<CardGroup>
  <Card title="Screen Configuration Guide" href="./screen-configuration-guide" icon="display">
    **How to Approach Screen Configuration**

    Learn the systematic methodology for creating effective user interfaces:

    * User journey definition and analysis
    * Navigation pattern selection
    * Information architecture planning
    * Layout strategy implementation
    * Platform-specific adaptations
    * Validation and testing approaches
  </Card>

  <Card title="Best Practices" href="./best-practices" icon="star">
    **UI Designer Best Practices**

    Essential guidelines for creating accessible, performant interfaces:

    * User-centered design principles
    * Information architecture standards
    * Component usage excellence
    * [Accessibility compliance (WCAG 2.1)](../../platform-deep-dive/accessibility)
    * Testing and quality assurance
    * Maintenance strategies
  </Card>

  <Card title="Platform Considerations" href="./platform-considerations" icon="devices">
    **Platform-Specific Guidelines**

    Comprehensive platform optimization and limitation reference:

    * Web, iOS, and Android design patterns
    * Performance optimization strategies
    * Platform-specific constraints and workarounds
    * Security and privacy considerations
    * Cross-platform testing protocols
  </Card>

  <Card title="Latest Features" href="#latest-features" icon="sparkles">
    **Advanced UI Designer Capabilities**

    Discover the features in FlowX.AI UI Designer:

    * Conditional styling for dynamic interfaces
    * Platform-specific configuration and overrides
    * Advanced form components with validation
    * Navigation areas integration
    * Flexible layout configuration and reusable templates
  </Card>
</CardGroup>

## Latest features

FlowX.AI UI Designer includes several advanced features for creating rich, interactive user interfaces:

<AccordionGroup>
  <Accordion title="Conditional Styling" icon="palette">
    **Dynamic Styling Based on Data**

    * Apply styles conditionally based on process data
    * Available for Text, Link, and Container elements
    * Real-time evaluation with priority handling
    * Platform-specific styling overrides

    **Configuration**:

    * Navigate to Styles tab → Conditional Styling section
    * Add expressions and effects using JS Editor
    * Define conditions and style overrides

    <Tip>
      Use conditional styling to highlight data patterns, outliers, or trends directly within the interface, reducing the need for multiple prototypes.
    </Tip>
  </Accordion>

  <Accordion title="Platform-Specific Configuration" icon="devices">
    **Multi-Platform Design Support**

    * Universal configuration and styling across Web, iOS, and Android
    * Platform-specific property overrides
    * Generic settings with targeted customizations
    * Import/export overrides between platforms

    **Key Features**:

    * Settings tab with platform selection
    * Override system for properties and expressions
    * Preview across different platforms
    * Consistent yet platform-optimized experiences
  </Accordion>

  <Accordion title="Advanced Form Components" icon="clipboard-list">
    **Rich Form Element Support**

    * Input fields with validation (required, custom)
    * Select components with CHANGE event handling
    * Checkboxes and radio buttons with dynamic behavior
    * File upload components with platform considerations
    * Date pickers and sliders for enhanced input

    **Validation Features**:

    * Required field validation
    * Custom validation rules
    * Conditional validation based on other fields
    * Real-time validation feedback
  </Accordion>

  <Accordion title="Navigation Areas Integration" icon="sitemap">
    **Enhanced Navigation Design**

    * Navigation areas accessible within UI Designer
    * Platform-specific navigation capabilities
    * Web: Full zones with headers/footers, wizard navigation
    * Mobile: Basic navigation areas with screen titles
    * Copy/paste navigation areas for consistency
  </Accordion>

  <Accordion title="Layout Configuration" icon="layout">
    **Flexible Layout System**

    * Linear layout with direction, justify, align controls
    * Grid layout support for complex designs
    * Gap settings for proper spacing
    * Wrap functionality for responsive behavior
    * Available for containers and grouping components
  </Accordion>

  <Accordion title="Reusable UI Templates" icon="layers">
    **Component Reusability**

    * Create modular UI components for reuse across processes
    * Template hierarchy with data model support
    * Input/output parameter mapping
    * Visual components and layout focus
    * Cannot include complex business logic
  </Accordion>
</AccordionGroup>

## UI components

FlowX offers a wide range of [UI components](./ui-designer#ui-components) that can be customized using the UI Designer. For example, when configuring a [card](./ui-component-types/root-components/card) element (which is a root component), the following properties can be customized:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_ui_designer.gif)

### Settings tab

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/uI_designer_panel1.png)
</Frame>

#### Generic tab

This is where you configure the logic and assign process keys, event handlers, and other component settings that are common across all platforms (Web, iOS, Android).

#### Platform-specific settings

For example, on Android, you might want to change the Card title to a shorter one.

To override a general property like a title, follow these steps:

<Steps>
  <Step title="Go to UI Designer">
    Access the UI Designer and select a UI Element, such as a **Card**.
  </Step>

  <Step title="Access platform-specific settings">
    From the UI Designer navigation panel, select the **Settings** tab, then select the **desired platform**
  </Step>

  <Step title="Perform the override">
    Click the "+" button (next to "Overrides") and select **Properties -> Title**, then input your desired value.

    <Tip>
      Settings overrides can always be imported/pushed from one platform to another:

      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
    </Tip>
  </Step>

  <Step title="Preview your changes">
    Preview your changes in the UI Designer by navigating from one platform to another or by comparing them.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/props_ui_designer_override.gif)
</Frame>

<Info>
  Keep in mind that the preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view.
</Info>

#### Hide expressions

By utilizing **Overrides** in the **Settings** tab, you can selectively hide elements on a specific platform.

To achieve this:

<Steps>
  <Step>
    Select a UI component in the **UI Designer**, then navigate to **Settings** -> **your desired platform** -> **Overrides (+)** -> **Expressions** -> **Hide**.
  </Step>

  <Step>
    Add your JavaScript Hide condition.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/hide_condition.gif)
</Frame>

## Permission-based expressions

Control UI element visibility and interaction based on user roles and process data.

<Card title="Permission-based expressions" href="../process/permission-based-expressions" icon="shield-check">
  Complete guide to configuring role-based UI permissions, cross-swimlane references, and collaborative workflows
</Card>

### Quick configuration

<Steps>
  <Step title="Enable multiple executors">
    In process settings, enable **Allow multiple executors** for your swimlane.
  </Step>

  <Step title="Select component">
    In **UI Designer**, select the component to configure.
  </Step>

  <Step title="Add condition">
    Expand **Permissions** section and click **+** to add hide or disable conditions.
  </Step>

  <Step title="Configure parameters">
    Set **Type** (USERNAME/ROLE), **Operator** (IN/NOT\_IN), **Value Type**, and **Value**.
  </Step>
</Steps>

<Tip>
  Use `CONFIGURATION_SWIMLANE_ROLE` for swimlane roles and `PROCESS_DATA` for dynamic values. `SWIMLANE_OWNER` requires no value.
</Tip>

### Styles tab

The Styles tab functions independently for three platforms: Web, iOS, and Android. Here, you can customize styles for each UI component on each platform.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_designer_panel2.png)
</Frame>

If you want to customize the appearance of a component to differ from the theme settings, you must apply a **Theme Override**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styless.gif)

<Info>
  Theme overrides can be imported from one platform to another.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styles.png)
</Info>

<Card title="Theme Management" href="../../flowx-designer/design-assets/themes" icon="link" />

#### Copy/paste styles

Contextual menu functionality enables efficient style management:

* **Copy Style**: Copy styling properties between compatible components
* **Paste Style**: Apply copied styles to selected components
* **Copy to/from Platform**: Share styles across Web, iOS, and Android platforms
* **Multiple selection**: Apply styles to multiple components simultaneously

Compatible component groups for style copying:

* **Input-like**: Input, Select, Datepicker, Textarea, Multiselect
* **Selection**: Radio, Checkbox
* **Container**: Container, Form, Card, Collection, Collection Prototype
* **Action**: Button, File Upload

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/copy_styles.png)
</Frame>

#### Copy/paste platform actions

### Preview

When you are editing a process in **UI Designer** you have the possibility of having the preview of multiple themes:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/preview_theme_ui_designer.gif)
</Frame>

<Info>
  Overrides are completely independent of the theme, regardless of which theme you choose in the preview mode.
</Info>

### Layout

There are two main types of layouts for organizing child elements: **Linear** and **Grid**.

* **Linear Layout**: Arranges child elements in a single line, either horizontally or vertically. Ideal for simple, sequential content flow.
* **Grid Layout**: Organizes elements into a structured grid with multiple columns and rows, useful for more complex, multi-dimensional designs.
* **Platform-Specific Layouts**: You can customize layout settings per platform (e.g., Grid on web, Linear on mobile) to ensure optimal responsiveness.

<Info>
  Both layouts offer options to customize direction, alignment, spacing, and wrap behavior for flexibility in design.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/set_linear.png)
</Frame>

<Card title="Layout" href="layout-configuration" icon="scroll" />

### Sizing

By setting desired values for these props, you can ensure that all UI elements on the interface are the desired size and perfectly fit with each other.

When adjusting the Fit W and Fit H settings, you can control the size and shape of the elements as they appear on your screen:

* Fit W: fill, fixed or auto
* Fit H: fill, fixed or auto

<Frame>
  ![UI element sizing options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_sizing.gif)
</Frame>

### Spacing

Margin and padding are CSS properties used to create space between elements in a web page:

* **margin** - the space outside an element
* **padding** - the space inside an element

<Frame>
  ![UI element spacing options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_spacing.gif)
</Frame>

<CardGroup>
  <Card title="Margin" href="https://www.w3schools.com/css/css_margin.asp" icon="link" />

  <Card title="Padding" href="https://www.w3schools.com/css/css_padding.asp" icon="link" />
</CardGroup>

### Advanced

* **Advanced** - for advanced customization, you can add CSS classes to pre-defined components, this option is available under the **Advanced** section
* **Data Test ID** - add custom test identifiers for automated testing and element interaction

By utilizing these styling options in FlowX.AI, you can create unique and visually appealing interfaces that meet your design requirements.

#### Data Test ID

The Advanced section includes a **Data Test ID** field, allowing you to assign custom identifiers to UI components. This feature enhances automated testing by providing meaningful, easily identifiable selectors for UI elements.

Key benefits:

* Replace auto-generated test IDs with custom, readable identifiers
* Simplify element targeting in test scripts

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-03-12%20at%2015.08.03.png)
</Frame>

## Tree view

The Tree View panel displays the component hierarchy, allowing you to navigate through the different levels of the interface.

Clicking on a specific component in the tree will highlight the selection in the editor, helping you locate and modify it.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_tree1.gif)

## UI component types

Different UI component types can be configured using UI Designer. The UI components are available and can be configured only using **user task nodes** or **navigation areas**.

<Info>
  Depending on the component type different properties are available for configuration.
</Info>

Understanding these component types will help you to better utilize the UI Designer tool and create rich web interfaces.

<AccordionGroup>
  <Accordion title="Layout (root components)" icon="object-group">
    * [Container](./ui-component-types/root-components/container)
    * [Card](./ui-component-types/root-components/card)
    * [Custom](./ui-component-types/root-components/custom)
  </Accordion>

  <Accordion title="Collection" icon="layer-group">
    * [Collection](./ui-component-types/collection/collection)
    * [Collection Prototype](./ui-component-types/collection/collection-prototype)
  </Accordion>

  <Accordion title="Basic" icon="list">
    * [Button](./ui-component-types/buttons)
    * [File Upload](./ui-component-types/buttons#file-upload)
    * [Image](./ui-component-types/image)
  </Accordion>

  <Accordion title="Typography" icon="font">
    * Text
    * Link
  </Accordion>

  <Accordion title="Forms" icon="object-ungroup">
    Form elements are a crucial aspect of creating user interfaces as they serve as the means of collecting information from the users. These elements come in various types, including simple forms, [inputs](./ui-component-types/form-elements/input-form-field), [text areas](./ui-component-types/form-elements/text-area), drop-down menus ([select](./ui-component-types/form-elements/select-form-field)), [checkboxes](./ui-component-types/form-elements/checkbox-form-field), [radio buttons](./ui-component-types/form-elements/radio-form-field), toggle switches ([switch](./ui-component-types/form-elements/switch-form-field)), [segmented buttons](./ui-component-types/form-elements/segmented-button), [sliders](./ui-component-types/form-elements/slider) and [date pickers](./ui-component-types/form-elements/datepicker-form-field). Each of these form elements serves a unique purpose and offers different options for capturing user input.

    * Form
    * [Input](./ui-component-types/form-elements/input-form-field)
    * [Textarea](./ui-component-types/form-elements/text-area)
    * [Select](./ui-component-types/form-elements/select-form-field)
    * [Checkbox](./ui-component-types/form-elements/checkbox-form-field)
    * [Radio](./ui-component-types/form-elements/radio-form-field)
    * [Switch](./ui-component-types/form-elements/switch-form-field)
    * [Segmented button](./ui-component-types/form-elements/segmented-button)
    * [Slider](./ui-component-types/form-elements/slider)
    * [Datepicker](./ui-component-types/form-elements/datepicker-form-field)
  </Accordion>

  <Accordion title="Indicators" icon="arrow-pointer">
    * [Message](./ui-component-types/indicators)
  </Accordion>
</AccordionGroup>

Navigation areas

<Accordion title="Navigation" icon="bars">
  * Page
  * Stepper
  * Step
  * Modal
  * Container
</Accordion>


# Fonts
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/design-assets/font-files

Fonts management allows you to upload and manage multiple font files, which can be later utilized when configuring UI templates using the UI Designer.

## Default fonts

FlowX ships with the **Open Sans** font family preinstalled, available in the UI Designer without any upload step. The following weight + style combinations are included:

| Weight          | Normal                 | Italic                       |
| --------------- | ---------------------- | ---------------------------- |
| 300 (Light)     | OpenSans-Light.ttf     | OpenSans-LightItalic.ttf     |
| 400 (Regular)   | OpenSans-Regular.ttf   | OpenSans-Italic.ttf          |
| 600 (SemiBold)  | OpenSans-SemiBold.ttf  | OpenSans-SemiBoldItalic.ttf  |
| 700 (Bold)      | OpenSans-Bold.ttf      | OpenSans-BoldItalic.ttf      |
| 800 (ExtraBold) | OpenSans-ExtraBold.ttf | OpenSans-ExtraBoldItalic.ttf |

Any other typography needs to be uploaded as a custom font (see below).

***

## Managing fonts

The "Font Management" screen displays a table with uploaded fonts. The following details are available:

* **FontFamily**: The names of the uploaded font families.
* **File Name**: The name of the font file.
* **Weight**: The weight of the font, represented by a numeric value.
* **Style**: The style of the font, such as "italic" or "normal".
* **Actions**: This tab contains options for managing the uploaded fonts, such as deleting or downloading them.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/fonts4.5.0.png)
</Frame>

## Uploading fonts

### Uploading theme font files

To upload new theme font files, follow these steps:

1. Open **FlowX.AI Designer**.
2. Navigate to the **Content Management** tab and select **Font files**.
3. Click **Upload font** (the **+** button) and choose a valid font file.

<Info>
  The accepted font format is TTF (TrueType Font file). **Only static TTF fonts are supported**. Variable fonts (dynamic fonts with adjustable width/weight in a single file) are not supported.
</Info>

<Warning>
  Each font weight and style combination requires a separate TTF file. For example, if you need "Open Sans" in regular (400), bold (700), and italic styles, you must upload separate TTF files for each variant.
</Warning>

4. Optionally, follow this naming convention for better compatibility: `[font family]-[font weight][font style]` (for example, `OpenSans-700Italic.ttf`).
5. Click **Upload**. You can upload multiple TTF font files.
6. For each uploaded font file, the system will automatically extract information such as font family, weight, and style from the file metadata.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/fonts-metadata.png)

## Exporting fonts

You can use the export feature to export a JSON file containing all the font files.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/export_fonts.png)

The exported JSON will look like this:

```json theme={"system"}

{
  "fonts": [
    {
      "fontFamily": "Open Sans",
      "filename": "OpenSans-ExtraBoldItalic.ttf",
      "weight": 800,
      "style": "italic",
      "size": 135688,
      "storagePath": "https://d22tnnndi9lo60.cloudfront.net/devmain/flowx/fonts-folder/1690383294848_OpenSans-ExtraBoldItalic.ttf",
      "contentType": "font/ttf",
      "application": "flowx",
      "flowxUuid": "ce0f75e2-72e4-40e3-afe5-3705d42cf0b2"
    },
    {
      "fontFamily": "Open Sans",
      "filename": "OpenSans-BoldItalic.ttf",
      "weight": 700,
      "style": "italic",
      "size": 135108,
      "storagePath": "https://d22tnnndi9lo60.cloudfront.net/devmain/flowx/fonts-folder/1690383295987_OpenSans-BoldItalic.ttf",
      "contentType": "font/ttf",
      "application": "flowx",
      "flowxUuid": "d3e5e2a0-958a-4183-8625-967432c63005"
    }
    //...

     ],
      "exportVersion": 1
}

```

## Importing fonts

You can use the import feature to import a **JSON file** containing font files from another environment. This is useful for transferring your font library between different environments (for example, from development to production).

<Info>
  **Important distinction**:

  * **Import** = Upload a JSON file exported from another environment (bulk transfer of fonts)
  * **Upload font** (+) = Add individual TTF font files one by one
</Info>

If a font file already exists in the target environment, you will be notified.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/import_fonts.png)

## Using fonts in UI Designer

For example, for an input UI element you can customize the typography by changing the following properties:

* Label:
  * Font family
  * Style and weight
  * Font line size (px)
  * Font line height (px)

* Text:
  * Font family
  * Style and weight
  * Font line size (px)
  * Font line height (px)

* Helper & errors:
  * Font family
  * Style and weight
  * Font line size (px)
  * Font line height (px)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/usinf_fonts.gif)


# Global Media Library
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/design-assets/global-media-library

System assets serve as a centralized hub for managing and organizing various types of media files outside an application, used on themes, including images, GIFs, and more.

<Frame>
  ![Global Media Library](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/global_media_library.png)
</Frame>

# 🌐 Global Media Library

This section is accessible from the left-side navigation under:

> **FlowX.AI Designer → Design Assets → Global Media Library**

***

## 📁 Media Library overview

The main **Media Library** interface displays all uploaded media assets in a table format with the following columns:

* **Preview**: Thumbnail preview of the asset.
* **Key**: A unique identifier for the asset.
* **Format**: File type (e.g., SVG, PNG).
* **Size**: File size.
* **Used as icon**: Indicates if the asset is used as a global icon (✓ if true).

<Frame>
  ![Use As Icon](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/use_as_icon.png)
</Frame>

* **Edited by**: User who last modified the asset.
* **Edited at**: Timestamp of the last modification.

Each asset row also includes:

* ✏️ **Edit icon**: To update the asset.
* ⋮ **More actions menu**: For additional options.

***

## ➕ Adding a New Asset

To add a new media asset:

1. Click the **blue plus (+)** button in the top-right corner.
2. In the **Add new item** dialog:
   * Click **Upload item** to select a file from your device.
   * Enter a **Key** for the asset.
3. Click **Add** to upload the item to the library.

<Tip>
  **Important:** The key must be unique and **cannot** be changed later. Choose it carefully.
</Tip>

***

## 📥 Import and Export

Click the **⋮ menu** next to the + button to access:

* **Import media assets**: Bulk upload multiple media files.
* **Export all**: Download all media assets as a ZIP archive.

***

## 🔍 Search Functionality

Use the **Search item by key** bar at the top to find media assets quickly. Results are filtered as you type.

***

## 📌 Icon Usage

If an asset is marked with a ✓ under the **Used as icon** column, it is actively used as a global icon across the FlowX.AI platform.


# Themes
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/design-assets/themes

Theme management enables you to change the appearance and styling of your app. Personalize the look and feel to match your branding, preferences, or specific requirements.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/themes4.5.0.png)
</Frame>

## Key features of theme management

1. **Theme Management:**
   * Creation, editing, and management of themes.
   * Selection of predefined themes or customization of themes from scratch.

2. **Customization Options:**
   * Modification of color schemes, typography, spacing, and visual effects.
   * Upload of custom assets like fonts and icons.

3. **Overrides and Variations:**
   * Ability to override default UI components styles properties on specific elements or sections.
   * Creation of different themes to accommodate different users/clients preferences.

4. **Platform Consistency:**
   * Consistency of theme styles across different platforms and devices.

5. **Preview:**
   * Real-time visualization of theme changes.

6. **Export/Import Functionality:**
   * Export of themes for backup, sharing, or reuse across multiple environments (UAT, DEV, etc.).
   * Import of exported from other environments.

## Creating a new theme

<Info>
  You have two options for creating the theme. You can import a theme that was exported from another environment (for example, your UAT/DEV) or to manually create it.
</Info>

To successfully create a new theme in FlowX.AI Designer, follow these steps:

<Steps>
  <Step title="Initiating theme creation">
    Locate the "Create New" button positioned above the right of the **Themes** list table.
  </Step>

  <Step title="Inputting theme details">
    Click the "Create New" button and enter  details for your theme:

    * **Theme Name** - pick a name for your theme
    * **Font Family** - select your desired font family, by default, the system provides "Open Sans"

    <Tip>
      If you wish to add a new font, click on the link provided under the **Font Family** field, which redirects you to the **Fonts management** Selection.
    </Tip>

    * **Choose your primary color** - the default color is `#006BD8`.

    <Check>
      Verify that the color format is in **HEX**. If not, an error message will indicate "Please insert a HEX color."
    </Check>
  </Step>
</Steps>

<Frame>
  <video />
</Frame>

## Configuring a new theme

After creating a theme, you must configure it. To configure your theme effectively, follow these steps:

<Steps>
  <Step title="Access theme settings">
    * Navigate to the settings or customization section of your app (in the UI Designer).
    * Look for options related to styling and think of an overall design
  </Step>

  <Step title="Customize theme settings">
    <Info>
      The Themes styles mechanism is based on hierarchy. In this hierarchy we have the following elements: Design Tokens, Global Settings and Components.
    </Info>

    Modify color schemes (using the design tokens), typography, spacing, and other visual elements to match your desired look and feel.
    Use the provided tools or controls to adjust theme settings. This might include sliders, color pickers, or dropdown menus.

    <AccordionGroup>
      <Accordion title="Design Tokens" icon="pen-ruler">
        <Info>
          **The Design Tokens** represent values based on which the theme is built.
        </Info>

        * **Color Palette, Shadows, Typography Tokens**: Configure these tokens based on your company's brand guidelines. They ensure reusability and consistency.

        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/design_tokens_theme.gif)
      </Accordion>

      <Accordion title="Global Settings" icon="gears">
        <Info>
          The **Global Settings** are properties that inherit values from the **Design Tokens** and sit on the top of the hierarchy. These properties are then inherited by the **Components**.
        </Info>

        * **Platform-specific Settings**: Configure settings for each platform (web, iOS, Android) based on the global settings you've defined.
        * **Styles and Utilities**: General settings applying to all components (styles) and labels, errors, and helper text settings (utilities).

        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/global_settings_theme.gif)
      </Accordion>

      <Accordion title="Component-level configuration" icon="hammer">
        <Info>
          When setting up your theme, remember that different platforms like web, iOS, and Android have their own settings. You need to configure each platform separately. Only color settings are the same across all platforms.
        </Info>

        <Tip>
          For example, you can configure a web theme, and then use the push and import options. You can push from the web the same configuration to iOS or Android.
        </Tip>

        **Component-level Configuration**: Customize the style of each component type.

        <Info>
          Keep in mind, there are differences between platforms, for example, for button configuration there are different properties available. What you configure on a platform will not be inherited by the others.
        </Info>

        <Info>
          The theme includes a configurable **Modal** component. You can style the modal container (padding, gap, border width, border radius, shadow, background and border colors) and its header (padding, gap, alignment, icon color, title and subtitle text styles and colors, and the dismiss icon).
        </Info>

        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/platform-components.gif)
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Reviewing the changes (multi-platform)">
    * Before finalizing the theme configuration, it's crucial to review how the changes will appear across different platforms. This step ensures consistency and allows for platform-specific adjustments if needed.
    * You can do that by either using the preview feature from **Themes** or by using the preview mode in the **UI Designer** by switching to your preffered platform.

    <Warning>
      Keep in mind that the preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view.
    </Warning>
  </Step>
</Steps>

Here is a quick walkthrough video on how to create and configure a theme:

<Frame>
  <video />
</Frame>

## Managing themes - process level (theme overrides)

With the Overrides feature you have now the possibility to override default theme settings on specific elements or sections.

Use Theme Overrides in UI Designer to adjust styles or props for specific UI elements based on the desired platform (Web, iOS and Android).

<Info>
  All components can now be styled with token overrides, for color, typography and shadow settings defined in the theme.
</Info>

<Info>
  **Theme overrides** in **UI Designer** are applied to the component itself, rather than to specific themes. This means that when switching the view to another theme, the overrides persist and apply to the new theme as well.
</Info>

### Styles tab

The Styles tab functions independently for three platforms: Web, iOS, and Android. Here, you can customize styles for each UI component on each platform.

If you want to customize the appearance of a component to differ from the theme settings, you must apply a **Theme Override**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styless.gif)

<Info>
  Theme overrides can be imported from one platform to another.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styles.png)
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_designer_panel2.png)
</Frame>

<Info>
  Preview mode: In the UI Designer, overrides are entirely independent of the theme. Regardless of the theme selected in preview mode, you will see the applied override reflected at the UI Designer level.
</Info>

### Preview

When you are editing a process in **UI Designer** you have the possibility of having the preview of multiple themes:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/preview_theme_ui_designer.gif)
</Frame>

<Info>
  Overrides are completely independent of the theme, regardless of which theme you choose in the preview mode.
</Info>

## Using a Theme in the container application

To integrate the theme into your container application, follow these steps:

* Copy the unique identifier (UUID) associated with the theme.
* Set the copied UUID within your container application.
* By doing so, ensure that the renderers within your application can recognize and apply the specified theme.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/copy_uuid.gif)
</Frame>

## Exporting/importing a theme

The Export/Import functionality in the theme management system allows users to export themes for various purposes such as backup, sharing, or reuse across multiple environments.

Additionally, it enables importing themes previously exported from other environments, facilitating integration and continuity across design workflows.

<Warning>
  Import is restricted to internal FlowX.AI mechanisms only; themes from external sources like Figma or Zeplin are not supported.
</Warning>

### Exporting a theme

<Steps>
  <Step>
    Navigate to the **Theme Management** panel within FlowX.AI Designer.
  </Step>

  <Step>
    Select the theme(s) you wish to export.
  </Step>

  <Step>
    From the breadcrumbs menu on the right, select **Export Theme**.
  </Step>

  <Step>
    The exported theme is saved in a standard format (JSON) and can be downloaded to a local directory or storage location.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/exporting_a_theme.gif)
</Frame>

### Importing a theme

<Steps>
  <Step>
    Navigate to the **Theme Management** panel within FlowX.AI Designer.
  </Step>

  <Step>
    From the contextual menu on the right, select **Import Theme**.
  </Step>

  <Step>
    Import it as a new theme or if the theme already exists in other environment, you can override it.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_a_theme.gif)
</Frame>

### Setting a default theme

You can establish a default theme by accessing the contextual menu on the right side of a theme and selecting "Set as Default."

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/default_th.png)
</Frame>

When a default theme is not set (or you haven't created a theme yet), the platform automatically assigns the FlowX.AI Theme, which is the platform's default theme. This ensures that there's always a default theme in place to provide a consistent appearance across processes and interactions within the app.

<Info>
  In case you select a specific default theme but later you delete it, the platform will revert to the FlowX.AI theme as the default. This safeguard ensures that there's always a default theme available, even if you remove your custom selection.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/2024-04-04%2019.00.33.gif)
  </Frame>
</Info>

Upon opening any process within the UI Designer, the default theme displays as the initial preview. This gives you a clear starting point and ensures consistency in the appearance of the process until you apply further customization.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/default2.png)
</Frame>

When creating a new process, you will notice the Default Theme (*FlowXTheme*) as the default preview.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/default1.png)
</Frame>

<Info>
  Furthermore, when you start a process definition, the theme switch defaults to the default theme in the run process popup from the process definitions list. This ensures that the default theme is consistently applied during the execution of processes, maintaining visual coherence in user interactions.
</Info>


# Adding a new node
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/adding-a-new-node

Learn how to add and configure different node types to build process flows in FlowX.AI Designer.

Once you've created a process definition, the next step is to build your process flow by adding and connecting nodes. Nodes represent different steps, events, and decision points in your business process.

<Frame>
  ![Adding a new node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_add_new_node.gif)
</Frame>

## What is a BPMN node?

<Card title="BPMN node" icon="circle-question">
  A BPMN (Business Process Model and Notation) 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. Each node type has a specific purpose and configuration requirements.
</Card>

## Available node types

FlowX.AI supports a rich variety of BPMN node types that you can use to model your business processes:

### Flow control nodes

<CardGroup>
  <Card title="Start event" href="../../building-blocks/node/start-end-node" icon="circle">
    Marks the beginning of a process flow
  </Card>

  <Card title="End Event" href="../../building-blocks/node/start-end-node" icon="circle">
    Marks the conclusion of a process flow
  </Card>
</CardGroup>

### Activity nodes

<CardGroup>
  <Card title="Task Node" href="../../building-blocks/node/task-node" icon="gear">
    Executes automated tasks and business rules
  </Card>

  <Card title="User Task" href="../../building-blocks/node/user-task-node" icon="user">
    Creates user interfaces and handles user interactions
  </Card>

  <Card title="Send Message Task" href="../../building-blocks/node/message-send-received-task-node" icon="paper-plane">
    Sends data to external systems or services
  </Card>

  <Card title="Receive Message Task" href="../../building-blocks/node/message-send-received-task-node" icon="envelope">
    Receives data from external systems or services
  </Card>
</CardGroup>

### Gateway nodes

<CardGroup>
  <Card title="Exclusive gateway" href="../../building-blocks/node/exclusive-gateway-node" icon="diamond">
    Creates decision points with mutually exclusive paths
  </Card>

  <Card title="Parallel Gateway" href="../../building-blocks/node/parallel-gateway" icon="code-branch">
    Splits process flow into multiple concurrent paths
  </Card>
</CardGroup>

### Event nodes

<CardGroup>
  <Card title="Message event" href="../../building-blocks/node/message-events/" icon="comment">
    Captures interactions between different process participants
  </Card>

  <Card title="Timer Event" href=".../../building-blocks/node/timer-events/" icon="clock">
    Triggers actions based on time conditions or delays
  </Card>

  <Card title="Error Event" href="../../building-blocks/node/error-events" icon="triangle-exclamation">
    Manages error handling in processes
  </Card>
</CardGroup>

### Subprocess nodes

<CardGroup>
  <Card title="Call activity" href="../../building-blocks/node/call-subprocess-tasks/call-activity-node" icon="diagram-project">
    Calls and runs a subprocess within the main process
  </Card>

  <Card title="Start Embedded Subprocess" href="../../building-blocks/node/call-subprocess-tasks/start-embedded-subprocess" icon="folder-tree">
    Initiates subprocesses embedded within a parent process
  </Card>
</CardGroup>

### Boundary event nodes

<CardGroup>
  <Card title="Message catch boundary event" href="../../building-blocks/node/boundary-events" icon="border-all">
    Waits for a specific message during task execution
  </Card>

  <Card title="Timer Boundary Event" href="../../building-blocks/node/message-events/message-catch-boundary-event" icon="stopwatch">
    Triggers based on time conditions during task execution
  </Card>

  <Card title="Error Boundary Event" href="../../building-blocks/node/error-events#configuring-an-error-intermediate-boundary-event" icon="exclamation">
    Catches errors during task or subprocess execution
  </Card>
</CardGroup>

<Info>
  Boundary events can only be attached to certain node types:

  * User Task
  * Service Task
  * Send Message/Receive Message Tasks
  * Subprocess (Embedded and Call Activity)
</Info>

For more information on BPMN node types and BPMN standards, see the following resources:

<CardGroup>
  <Card title="BPMN Node Documentation" href="../../building-blocks/node/node" icon="file-lines">
    BPMN node types in FlowX.AI
  </Card>

  <Card title="Intro to BPMN" href="../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn" icon="diagram-project">
    Learn fundamental BPMN concepts and standards
  </Card>
</CardGroup>

For a comprehensive understanding of BPMN standards and concepts, see [BPMN 2.0 Basic Concepts](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn).

<Card title="BPMN 101" href="https://academy.flowx.ai/explore/bpmn-101" icon="school">
  Learn more about BPMN and how it's used in FlowX through our Academy course
</Card>

## Adding a node to your process

<Steps>
  <Step title="Access Your Process Definition">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Go to the **Processes** section within your project
    3. Click on the process definition you want to edit
  </Step>

  <Step title="Add a Node to the Canvas">
    1. Locate the node palette on the left side of the screen
    2. **Drag and drop** your desired node type onto the canvas
    3. Position the node where you want it in your process flow

    <Tip>
      Organize your process flow from left to right for better readability. Place related nodes closer together to show their relationship.
    </Tip>
  </Step>

  <Step title="Connect Nodes with Sequence Flows">
    To create a connection between nodes (called a sequence flow):

    1. Click on the source node to select it
    2. Click the **arrow** icon that appears
    3. Click on the target node you want to connect to
    4. A sequence flow arrow will be created between the two nodes

    <Frame>
      ![Connect nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_sequence.png)
    </Frame>

    <Warning>
      Every node (except End nodes) must have at least one outgoing sequence flow, and every node (except Start nodes) must have at least one incoming sequence flow for the process to be valid.
    </Warning>
  </Step>

  <Step title="Configure Node Properties">
    After adding a node, you need to configure its properties:

    1. Click on the node to select it to open the properties panel
    2. Click edit icon to open the properties panel
    3. Configure basic properties like name and description
    4. Set node-specific properties depending on the node type
    5. Configure actions for the node

    <Frame>
      ![Node edit menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_edit_menu.png)
    </Frame>

    <Frame>
      ![Node properties](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_config.png)
    </Frame>

    <Info>
      Different node types have different configuration options. For example, Gateway nodes have condition-related settings.

      <Frame>
        ![Gateway configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gateway_config.png)
      </Frame>
    </Info>
  </Step>

  <Step title="Add Actions to Nodes">
    For nodes that support actions (task nodes, user task nodes, and message nodes):

    1. Select the node
    2. In the properties panel, navigate to the **Actions** section
    3. Click **+ Add Action**
    4. Select the action type and configure its parameters

    <Frame>
      ![Add action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_action.png)
    </Frame>

    <Note>
      Actions allow you to incorporate business rules, save data, send messages, and interact with users. Learn more about [Node Actions](../../building-blocks/actions/actions).
    </Note>
  </Step>
</Steps>

## Common node configuration options

While each node type has specific properties, many share these common configuration options:

<AccordionGroup>
  <Accordion title="Basic Properties">
    * **Name**: A descriptive name for the node (visible in the Process Designer).
    * **Can go back**: Option available in various nodes that controls whether users can return to previous steps in a process. When enabled (set to true), it allows users to revisit and redo that step after completing it.
    * **Stage**: The stage of the process the node belongs to.
  </Accordion>

  <Accordion title="Action Properties">
    For nodes that support actions:

    * **Action Type**: Type of action to execute
    * **Action Parameters**: Configuration for the specific action
    * **Execution Order**: Sequence for multiple actions on a node
  </Accordion>
</AccordionGroup>

## Node type-specific configuration

<CardGroup>
  <Card title="User Task Configuration" icon="user-gear">
    * UI Component selection
    * Form configuration
    * Data validation rules
    * Task assignment settings
  </Card>

  <Card title="Gateway Configuration" icon="code-branch">
    * Condition expressions
    * Default sequence flow
    * Branch naming
    * Gateway direction (diverging/converging)
  </Card>

  <Card title="Message Task Configuration" icon="envelope-open-text">
    * Message format
    * Target system
    * Correlation keys
    * Timeout handling
  </Card>

  <Card title="Service Task Configuration" icon="gears">
    * Service implementation
    * Input/output mapping
    * Error handling
    * Execution parameters
  </Card>
</CardGroup>

## Best practices

<Tip>
  **When adding nodes to your process:**

  * **Use descriptive names** for nodes to make the process easier to understand
  * **Organize the layout** from left to right for better readability
  * **Limit the number of sequence flows** from a single node to maintain clarity
  * **Group related functionality** into subprocesses to reduce complexity
  * **Document assumptions and decisions** in node descriptions
  * **Validate your process** regularly during development to catch errors early
</Tip>

## Next steps

After adding nodes to your process, you can:

<Card title="Add Actions to Nodes" icon="plus" href="../managing-a-project-flow/adding-an-action-to-a-node">
  Configure business rules and actions for your nodes
</Card>


# Adding an action to a node
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/adding-an-action-to-a-node

Learn how to enhance your process flows by adding actions to nodes for business rules, data management, and integration with external systems.

Actions are elements that bring your process nodes to life by adding business logic, data management capabilities, and integration with external systems. They define the specific activities that nodes perform within your process flow.

<Frame>
  ![Adding a node action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_add_node_action.gif)
</Frame>

## What is a node action?

<Card title="Node Action" icon="circle-question">
  A node action defines the specific activity that a node performs within a process flow. Actions allow you to incorporate business rules, manage data, communicate with external systems, and control what gets displayed in the user interface. They are the building blocks that drive your process logic and user interactions.
</Card>

<CardGroup>
  <Card title="Actions Documentation" href="../../building-blocks/actions" icon="file-lines">
    Comprehensive documentation on all action types and their configurations
  </Card>

  <Card title="Business Rules" href="../../building-blocks/actions/business-rule-action/business-rule-action" icon="code">
    Learn how to implement business logic with rule actions
  </Card>
</CardGroup>

## Action types

FlowX.AI supports several types of actions that can be added to nodes, broadly categorized into business rules and user interactions:

### Business rules and data management

<CardGroup>
  <Card title="Business Rule" icon="code">
    Add custom logic and decision-making using scripts
  </Card>

  <Card title="Save Data" icon="database">
    Persist process data to storage
  </Card>

  <Card title="Kafka Send" icon="paper-plane">
    Send messages to Kafka topics for event-driven scenarios
  </Card>

  <Card title="Upload File" icon="file-arrow-up">
    Handle file uploads within the process flow
  </Card>
</CardGroup>

### Process control and integration

<CardGroup>
  <Card title="Start Subprocess" icon="diagram-project">
    Initiate a subprocess from within the current process
  </Card>

  <Card title="Append Params to Parent Process" icon="arrow-up-right-dots">
    Pass data back to a parent process from a subprocess
  </Card>

  <Card title="Start Integration Workflow" icon="plug">
    Trigger an integration workflow with external systems
  </Card>

  <Card title="Start New Project Instance" icon="folder-plus">
    Launch a new project instance from within a process
  </Card>
</CardGroup>

### User interface

<CardGroup>
  <Card title="Send Data to User Interface" icon="display">
    Send data to be displayed in front-end applications
  </Card>
</CardGroup>

<Note>
  Actions can only be added to certain node types:

  * Task nodes (Service Tasks)
  * User Task nodes
  * Send Message/Receive Message Task nodes
</Note>

## Adding an action to a node

<Steps>
  <Step title="Access Your Process Definition">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Go to the **Processes** section within your project
    3. Select your process definition from the list
    4. Click the **Edit Process** button to open the Process Designer
  </Step>

  <Step title="Select or Add a Node">
    1. Either select an existing node that supports actions, or add a new one
    2. Remember that only Task nodes, User Task nodes, and Message Task nodes support actions

    <Info>
      If you need to add a new node first, refer to the [Adding a New Node](./adding-a-new-node) documentation.
    </Info>
  </Step>

  <Step title="Add an Action">
    1. With the node selected, locate the **Actions** section in the properties panel
    2. Click the **+ Add Action** button
    3. From the dropdown menu, select the action type you want to add

    <Frame>
      ![Adding a node action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_add_node_action.gif)
    </Frame>
  </Step>

  <Step title="Configure Action Parameters">
    Each action type requires specific configuration parameters:

    1. Fill in the required fields for your selected action type
    2. Configure optional parameters as needed
    3. Save your changes

    <Frame>
      ![Action parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/actions_paramss.png)
    </Frame>

    <Warning>
      Pay careful attention to parameter syntax and formatting. Incorrect configurations may cause the action to fail during process execution.
    </Warning>
  </Step>

  <Step title="Set Action Execution Order (Multiple Actions)">
    If you have multiple actions on a single node:

    1. Use the drag handles to arrange the actions in the desired execution order
    2. Actions will execute from top to bottom in the list
    3. Consider dependencies between actions when setting the order

    <Tip>
      For complex nodes with multiple actions, consider adding comments in scripts or descriptions to document the purpose and dependencies of each action.
    </Tip>
  </Step>

  <Step title="Save Your Process">
    Click the **Save** button to save your process definition with the new action.
  </Step>
</Steps>

## Common action configurations

Different action types require different configurations, but many share these common elements:

<AccordionGroup>
  <Accordion title="Business Rule Action">
    * **Name**: Descriptive identifier for the rule
    * **Script Type**: JavaScript or other supported languages
    * **Script Content**: The business logic to execute
    * **Input Parameters**: Data inputs to the script
    * **Output Parameters**: Data returned from the script
  </Accordion>

  <Accordion title="Save Data Action">
    * **Process Variables**: The data to be saved
    * **Target Storage**: Where the data should be persisted
    * **Data Mapping**: How process data maps to storage fields
  </Accordion>

  <Accordion title="Kafka Send Action">
    * **Topic**: The Kafka topic to send messages to
    * **Key**: Identifier for the message
    * **Value**: The data payload to send
    * **Headers**: Additional message metadata
  </Accordion>

  <Accordion title="Send Data to User Interface">
    * **UI Component**: The target component to update
    * **Data**: The information to display
    * **Formatting**: Display options for the data
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  **When adding actions to nodes:**

  * **Use meaningful action names** to clearly indicate their purpose
  * **Keep business rules focused** on a single responsibility
  * **Document complex logic** with comments in your scripts
  * **Consider error handling** in your action configurations
  * **Test actions individually** before relying on them in production flows
  * **Monitor performance** of actions that might be resource-intensive
  * **Use consistent data structure** across related actions for better maintainability
</Tip>

## Next steps

After adding actions to your nodes, you can:

<CardGroup>
  <Card title="Handling decisions in the flow" icon="diamond" href="../../flowx-designer/managing-a-project-flow/handling-decisions-in-the-flow">
    Learn how to implement conditional branching in your processes using exclusive gateways
  </Card>

  <Card title="Configure UI Components" icon="palette" href="../../flowx-designer/managing-a-project-flow/creating-a-user-interface">
    Design the user interface elements that will interact with your actions
  </Card>
</CardGroup>


# Adding parallel flow branches
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/adding-more-flow-branches

Learn how to create concurrent process flows using parallel gateways to execute multiple activities simultaneously.

In many business processes, certain activities can or should be performed simultaneously rather than sequentially. FlowX.AI's parallel gateway nodes allow you to split your process flow into multiple concurrent branches, enabling parallel execution of different activities.

<Frame>
  ![Parallel Gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/process_flowx_parallel.png#center)
</Frame>

## What is a parallel gateway?

<Card title="Parallel Gateway" icon="code-branch">
  A parallel gateway (also known as an AND gateway) creates multiple concurrent paths in your process flow. Unlike exclusive gateways which follow only one path, parallel gateways activate all outgoing paths simultaneously. This allows multiple activities to be performed in parallel, improving process efficiency.
</Card>

<CardGroup>
  <Card title="Parallel Gateway Documentation" href="../../building-blocks/node/parallel-gateway" icon="file-lines">
    Complete reference for parallel gateway configuration
  </Card>

  <Card title="Process Flow Tokens" href="../../building-blocks/token" icon="diagram-project">
    Learn more about how tokens drive process flow execution
  </Card>
</CardGroup>

## How parallel gateways work

<Frame>
  ![Parallel Branches Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/parallel_zn.png)
</Frame>

Parallel gateways function as fork and join points in your process:

1. **Fork (Diverging Gateway)**: Splits the process flow into multiple concurrent paths
2. **Parallel Execution**: All branches execute simultaneously and independently
3. **Join (Converging Gateway)**: Merges the parallel branches back into a single flow
4. **Synchronization**: The process waits until all parallel branches complete before proceeding

<Info>
  A process must have both a diverging parallel gateway (fork) and a converging parallel gateway (join) that brings all branches back together. All branches must be completed before the process can continue past the converging gateway.
</Info>

## Token behavior in parallel gateways

Tokens are fundamental to understanding how parallel flows work in FlowX.AI:

<Frame>
  ![Token Flow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/token_parallel.png)
</Frame>

<Steps>
  <Step title="Token Creation">
    When a process reaches a parallel gateway, the gateway creates child tokens for each outgoing branch. Each branch receives its own token.
  </Step>

  <Step title="Independent Execution">
    Each child token advances through its respective branch independently, proceeding from one node to the next based on the sequence and actions defined in the process.
  </Step>

  <Step title="Token Synchronization">
    A converging parallel gateway waits for all child tokens to arrive. The parent token remains at this gateway until all child tokens have completed their respective paths.
  </Step>

  <Step title="Process Continuation">
    Once all child tokens have arrived at the converging gateway, they are merged back into the parent token, and the process continues with a single token.
  </Step>
</Steps>

<Warning>
  If any parallel branch gets stuck or never completes, the entire process will wait indefinitely at the converging gateway. Always ensure all branches can complete successfully.
</Warning>

## Creating a flow with parallel branches

<Steps>
  <Step title="Create or Open a Process Definition">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Go to the **Processes** section and select your process or create a new one
    3. Click the **Edit Process** button to open the Process Designer
  </Step>

  <Step title="Add Basic Flow Elements">
    1. Add a **Start Node** to your process canvas (if creating a new process)
    2. Add initial nodes for any process steps that should occur before the parallel branches

    <Note>
      Plan your parallel branches carefully. Activities in parallel branches should be independent of each other and not rely on results from other branches.
    </Note>
  </Step>

  <Step title="Add the Diverging Parallel Gateway">
    1. From the node palette, drag a **Parallel Gateway** node onto your canvas
    2. Connect your previous node to this gateway
    3. Give your gateway a descriptive name (e.g., "Start Parallel Processing")
  </Step>

  <Step title="Create Parallel Branches">
    1. Add the nodes for each parallel branch that will execute simultaneously
    2. Connect the diverging parallel gateway to the first node of each branch
    3. Build out each branch with the necessary nodes and actions

    <Tip>
      You can have any number of parallel branches, but keep in mind that every branch must eventually connect to the converging gateway.
    </Tip>
  </Step>

  <Step title="Add the Converging Parallel Gateway">
    1. Add another **Parallel Gateway** node to the canvas
    2. Connect the last node of each parallel branch to this converging gateway
    3. Give this gateway a descriptive name (e.g., "Merge Parallel Branches")

    <Warning>
      Ensure that all parallel branches connect to the converging gateway. Missing connections will result in stuck processes.
    </Warning>
  </Step>

  <Step title="Complete the Process Flow">
    1. Add any additional nodes that should execute after the parallel branches
    2. Connect the converging gateway to the next node in your process
    3. Ensure your process eventually reaches an **End Node**
    4. Save your process definition
  </Step>
</Steps>

## Use cases for parallel gateways

Parallel gateways are ideal for the following scenarios:

<CardGroup>
  <Card title="Document Collection" icon="file-lines">
    Requesting multiple documents simultaneously from different systems or departments
  </Card>

  <Card title="Multi-Party Approval" icon="users">
    Collecting approvals from multiple stakeholders at the same time
  </Card>

  <Card title="Data Processing" icon="database">
    Performing multiple data operations or calculations in parallel
  </Card>

  <Card title="Background Checks" icon="shield-check">
    Running different validation or verification processes concurrently
  </Card>
</CardGroup>

## Best practices

<Tip>
  **When implementing parallel branches:**

  * **Use meaningful names** for parallel gateways to document their purpose
  * **Keep branches independent** of each other to avoid deadlocks or race conditions
  * **Balance work** across branches to optimize overall process execution time
  * **Consider timeouts** for branches that might get stuck or take too long
  * **Test all branches** thoroughly to ensure they can complete successfully
  * **Use data scoping** carefully to prevent data conflicts between branches
  * **Consider error handling** in each branch to prevent process deadlocks
</Tip>

## Common patterns

<CardGroup>
  <Card title="Simple Parallel Split-Join" icon="code-branch">
    Basic pattern with a diverging and converging gateway
  </Card>

  <Card title="Multi-Layer Parallel Processing" icon="network-wired">
    Nested parallel structures with gateways inside parallel branches
  </Card>

  <Card title="Parallel Tasks with Timeouts" icon="stopwatch">
    Parallel branches with timer events to handle potential delays
  </Card>

  <Card title="Collect and Merge" icon="diagram-merge">
    Parallel branches that gather different pieces of information for later consolidation
  </Card>
</CardGroup>

## Next steps

After implementing parallel branches in your process, you can:

<Card title="Creating a user interface" icon="palette" href="../../flowx-designer/managing-a-project-flow/creating-a-user-interface">
  Design the user interface elements that will interact with your actions
</Card>


# Creating and managing process definitions
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-new-process-definition

Learn how to create new process definitions and manage them using operations like export, duplicate, copy between projects, and view dependencies.

<video />

## What is a process definition?

A process definition is the core building block of the FlowX.AI platform, serving as the blueprint for a business process. It's composed of nodes linked by sequences that define the path and logic of your application's workflow.

<Info>
  A complete process definition must include at least one [START](../../building-blocks/node/start-end-node#start-node) and one [END](../../building-blocks/node/start-end-node#end-node) node to mark where the process begins and concludes.
</Info>

<CardGroup>
  <Card title="Executable Blueprint" icon="diagram-project">
    Process definitions can be instantiated, executed, and monitored within the platform
  </Card>

  <Card title="Business Logic Container" icon="gears">
    Houses all actions, decisions, user interfaces, and integrations for your business process
  </Card>

  <Card title="Event-Driven Flow" icon="sitemap">
    Nodes and sequences create a path for process tokens to follow based on conditions and events
  </Card>

  <Card title="Multi-Platform Support" icon="display">
    Process definitions can generate interfaces for web, mobile, and other platforms
  </Card>
</CardGroup>

## Creating a process definition

<Steps>
  <Step title="Access the Process Definitions Section">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Go to the **Processes** section within your project

    <Note>
      You must have already created a project before creating process definitions. Process definitions belong to projects and inherit project settings.
    </Note>
  </Step>

  <Step title="Create a New Process Definition">
    1. Click the **+ New Process** button in the top-right corner
    2. Enter a unique name for your process definition that clearly describes its purpose
    3. Optionally, add a description to provide context about what this process does
    4. Click **Create** to create the new process definition

    <Tip>
      Use a descriptive naming convention for your processes, such as "\[Department]-\[Function]-\[Action]" (e.g., "HR-Onboarding-Application").
    </Tip>

    <Frame>
      ![Process Definition Editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/create_new_process.png)
    </Frame>
  </Step>

  <Step title="Configure the Process Definition">
    After creating the process definition, you'll be automatically directed to the FlowX.AI Process Designer editor where you can start building your process flow.

    <Frame>
      ![Process Designer Empty Canvas](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/process_designer_empty.png)
    </Frame>
  </Step>

  <Step title="Add Start and End Nodes">
    Every process definition must have at least one START node and one END node:

    1. From the node palette on the left, drag a **START** node onto the canvas
    2. Configure the START node properties in the panel that appears
    3. Drag an **END** node onto the canvas
    4. Connect the nodes by clicking on the START node, selecting the arrow command, and then clicking on the END node

    <Warning>
      Without properly configured START and END nodes, your process won't be executable. The START node initializes the process, while the END node ensures proper process completion.
    </Warning>
  </Step>

  <Step title="Build Your Process Flow">
    Expand your process by adding additional nodes between the START and END nodes:

    1. Drag the appropriate node types from the palette onto the canvas
    2. Configure each node's properties and actions
    3. Connect nodes in the sequence they should execute
    4. Add conditions and gateways to create branching logic

    <CardGroup>
      <Card title="Task Nodes" icon="list-check">
        For business rules and automated actions
      </Card>

      <Card title="User Task Nodes" icon="user-gear">
        For user interactions and UI components
      </Card>

      <Card title="Gateways" icon="code-branch">
        For decision points and parallel flows
      </Card>
    </CardGroup>
  </Step>

  <Step title="Save Your Process Definition">
    Regularly save your work by clicking the **Save** button in the editor toolbar.

    <Info>
      Process definitions are saved within your project but need to be included in a project version and build to be deployed to environments.
    </Info>
  </Step>
</Steps>

## Key node types

When building your process definition, you'll use various node types to model your business logic:

<AccordionGroup>
  <Accordion title="Start and End Nodes">
    **Start Node**: Marks the beginning of a process flow, defining how a process instance is initiated.

    **End Node**: Marks the conclusion of a process flow, ensuring proper cleanup and completion.

    <Note>
      A process can have multiple START nodes (with different conditions) and multiple END nodes depending on the possible outcomes.
    </Note>
  </Accordion>

  <Accordion title="Task Nodes">
    **Task Node**: Used for executing automated actions without user interaction.

    **User Task Node**: Configures the UI components and collects data from users.

    **Send/Receive Message Tasks**: Used for communication with external systems and services.
  </Accordion>

  <Accordion title="Gateway Nodes">
    **Exclusive Gateway**: Creates decision points where the flow follows only one path based on conditions.

    **Parallel Gateway**: Splits the process into multiple parallel branches that execute simultaneously.

    **Inclusive Gateway**: Allows multiple paths to be taken based on conditions, unlike the exclusive gateway.
  </Accordion>

  <Accordion title="Special Nodes">
    **Subprocess Run Node**: Enables you to run a subprocess within the main process.

    **Timer Events**: Schedule actions to occur at specific times or after delays.

    **Message Events**: Handle message-based communication between processes.
  </Accordion>
</AccordionGroup>

## Adding actions to nodes

Nodes can have actions associated with them to perform specific operations:

<CardGroup>
  <Card title="Business Rules" icon="code">
    Execute logic, validate data, and make decisions
  </Card>

  <Card title="Data Operations" icon="database">
    Save, retrieve, and manipulate process data
  </Card>

  <Card title="Integration" icon="plug">
    Connect with external systems and services
  </Card>

  <Card title="UI Interactions" icon="display">
    Send data to and receive data from users
  </Card>
</CardGroup>

<Note>
  Actions can only be added to certain node types: task nodes, user task nodes, and send/receive message tasks.
</Note>

## Managing process definitions

After creating process definitions, you can manage them using the contextual menu available in the Processes list. Access this menu by clicking the three-dot icon (⋮) next to any process entry.

<Frame>
  ![Process management menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_dsg_cm.png)
</Frame>

<Info>
  **Two contextual menus available:**

  This menu is accessible from the **Processes list view** (before opening a process). There's also a separate contextual menu available when you're **inside** a process definition that provides operations like Clear Cache, Audit Log, View History, and Delete.
</Info>

<Card title="Operations inside process definitions" href="../../building-blocks/process/process-definition#access-additional-operations" icon="pen-ruler">
  Learn about the contextual menu available while editing a process definition
</Card>

### Configure process settings

Open the process settings interface to configure process-level options including permissions, platform selection, task management integration, and data search indexing.

**To configure a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Configure** from the menu
3. The settings panel opens, where you can modify:
   * Process name and general settings
   * Platform selection (Web, Mobile, Omnichannel)
   * Permissions and swimlane access control
   * Task management integration
   * Data search and indexing

<Card title="Process settings" href="../../building-blocks/process/process-definition#configure-process-settings" icon="sliders">
  Complete guide to all process configuration options
</Card>

### Export a process

Export a process definition to transfer it between environments, create backups, or share it with other teams.

**To export a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Export**
3. The system generates a downloadable package containing:
   * Process definition JSON
   * Process metadata and manifest files
   * Version information
4. Save the export file to your local system

**Export structure**:

When you export a process, FlowX.AI creates a structured folder:

* Root export folder with unique identifier
* Process subfolder with `manifest.json` and `metadata.json`
* Version subfolder with the process definition JSON file

<Tip>
  Use a clear naming convention for exported files such as `[ProcessName]_[Version]_[Date].zip` to help identify exports later.
</Tip>

<Warning>
  Exported process definitions may contain environment-specific configurations. Review and adjust these settings when importing to a different environment.
</Warning>

<Card title="Export and import guide" href="./export-import-a-process-definition" icon="arrow-right-arrow-left">
  Learn about importing exported processes
</Card>

### Duplicate a process

Create a copy of an existing process definition within the same project. This is useful when you want to create a variant of a process or use an existing process as a template.

**To duplicate a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Duplicate**
3. Enter a name for the duplicated process
4. Click **Confirm** to create the copy

**What gets duplicated**:

* Complete process flow with all nodes and sequences
* All node configurations and actions
* UI Designer configurations
* Data model structure
* Process settings (permissions, platform selection, etc.)

**What doesn't get duplicated**:

* Process instances and runtime data
* Audit history
* Version history

<Tip>
  Use duplication to create process variants for different departments or to test significant changes without affecting the original process.
</Tip>

<Info>
  The duplicated process is created in the current work-in-progress (WIP) version of your project. Remember to commit your changes when ready.
</Info>

### Copy to another project or library

Transfer a process definition to a different project or library within your FlowX.AI environment. This enables sharing reusable processes across multiple projects.

**To copy a process to another project**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Copy to another project/library**
3. Choose the destination project or library from the list
4. Optionally adjust the process name for the destination
5. Click **Confirm** to complete the copy operation

**Use cases**:

* **Create reusable components**: Move common processes to a shared library
* **Share across teams**: Copy processes to other team projects
* **Promote to production projects**: Transfer tested processes to production-ready projects
* **Create process templates**: Build a library of standard process templates

<Warning>
  Ensure all dependencies (subprocesses, data types, integrations) exist in the destination project, or copy them separately. Missing dependencies will cause errors.
</Warning>

<Info>
  Copying a process creates an independent copy. Changes to the original won't affect the copied version and vice versa.
</Info>

### See used resources

View all resources and dependencies that the process definition uses. This helps you understand the process's connections to other components and identify potential impacts when making changes.

**To view used resources**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **See used resources**
3. Review the list of dependencies, which may include:
   * Subprocesses and workflows
   * UI templates and components
   * Data model types
   * Integration connectors
   * Business rules and scripts
   * Document templates
   * Notification templates

**Benefits**:

* **Impact analysis**: Understand what will be affected by changes
* **Dependency tracking**: Ensure all required resources are available before deployment
* **Documentation**: Map relationships between processes and resources
* **Troubleshooting**: Identify missing or misconfigured dependencies

<Tip>
  Review used resources before exporting or copying a process to ensure you include all necessary dependencies in the target environment.
</Tip>

### View audit log

Access the comprehensive change history for the process definition, showing who made changes, when, and what was modified.

**To view the audit log**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Audit log**
3. Review the audit entries, which include:
   * Timestamp of each change
   * User who made the change
   * Application version
   * Event type and subject
   * Change status

**Audit log features**:

* **Filterable entries**: Search and filter by date, user, or event type
* **Complete audit trail**: Maintain compliance with regulatory requirements
* **Change tracking**: Identify when specific modifications were introduced
* **Troubleshooting**: Trace issues back to specific changes

<Card title="Audit documentation" href="../../platform-deep-dive/core-extensions/audit" icon="clock-rotate-left">
  Learn more about audit logging capabilities
</Card>

### View history

Access the version history of the process definition to see how it evolved across different committed versions.

**To view version history**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **View history**
3. Review the list of versions
4. Select two versions to compare changes side-by-side

**History capabilities**:

* **Version comparison**: See exactly what changed between any two versions
* **Change tracking**: Identify when specific features were added or modified
* **Rollback reference**: Understand previous configurations if you need to revert changes
* **Documentation**: Track the evolution of your process over time

<Info>
  Version history shows committed versions only. Changes in the current work-in-progress version appear after you commit the project version.
</Info>

<Card title="Project versioning" href="../../projects/managing-applications/versioning" icon="code-branch">
  Complete guide to version management
</Card>

### Delete a process

Remove a process definition from your project when it's no longer needed.

**To delete a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Delete**
3. Confirm the deletion in the dialog that appears

<Warning>
  **Use with extreme caution**: Deleting a process definition is a significant action with the following consequences:

  * The process definition is removed from the current work-in-progress (WIP) version
  * You cannot delete a process that's part of a committed version
  * Other processes that reference this one as a subprocess may break
  * The deletion can be recovered only from previous committed versions
</Warning>

**Before deleting a process**:

1. ✓ **Check for dependencies**: Use "See used resources" to identify processes that reference this one
2. ✓ **Review running instances**: Verify no critical process instances are currently active
3. ✓ **Backup if needed**: Export the process definition before deletion if you might need it later
4. ✓ **Update documentation**: Remove references to the deleted process from your documentation

**Impact of deletion**:

| Aspect                  | Impact                                                     |
| ----------------------- | ---------------------------------------------------------- |
| **Current WIP version** | Process is removed immediately                             |
| **Committed versions**  | Previous versions remain unchanged                         |
| **Running instances**   | Existing instances continue with their original definition |
| **Dependent processes** | May show errors or validation warnings                     |
| **Historical data**     | Process instance data in reporting is not affected         |

<Info>
  Deleted processes can be recovered by accessing previous committed versions through version history, but any uncommitted changes will be lost.
</Info>

## Best practices

<Tip>
  **Process Definition Design Tips**:

  * Start with a simple skeleton process with START and END nodes before adding complexity
  * Create a logical flow from left to right in your diagram for better readability
  * Group related activities into subprocesses to keep the main process clean
  * Use clear naming conventions for nodes and actions
  * Document your process design decisions within node descriptions
  * Test your process with simulated data before publishing
</Tip>

## Next steps

After creating your process definition, you can:

<CardGroup>
  <Card title="Add Nodes to Your Process" icon="circle-plus" href="./adding-a-new-node">
    Learn how to add and configure different node types
  </Card>

  <Card title="Create User Interfaces" icon="palette" href="./creating-a-user-interface">
    Build interactive UIs for your process
  </Card>

  <Card title="Process Definition Deep Dive" icon="book" href="../../building-blocks/process/process-definition">
    Comprehensive guide to process configuration and settings
  </Card>

  <Card title="Export and Import" icon="arrow-right-arrow-left" href="./export-import-a-process-definition">
    Transfer processes between environments
  </Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a process have multiple START nodes?">
    Yes, a process definition can have multiple START nodes, each with different starting conditions as long as they are on different swimlanes. This allows the same process to be initiated in different ways depending on the context.

    <Info>
      Process definition cannot contain multiple start nodes on the same swimlane.
    </Info>
  </Accordion>

  <Accordion title="How do I modify an existing process definition?">
    To modify an existing process, navigate to the Processes section in your project, find the process you want to edit, and click on it. Then click the "Edit Process" button to open it in the Process Designer.
  </Accordion>

  <Accordion title="Can I reuse parts of a process definition?">
    Yes, you can create reusable components as subprocesses, which can then be called from multiple main processes. This promotes reusability and maintainability. You can also duplicate existing processes or copy them to other projects using the contextual menu operations described in the Managing process definitions section above.
  </Accordion>

  <Accordion title="Can I export or import process definitions?">
    Yes, FlowX.AI allows you to export and import process definitions. Use the **Export** option from the process contextual menu to create a downloadable package. The export includes the process definition JSON, metadata, and version information in a structured format. See the [Export a process](#export-a-process) section above for detailed instructions.
  </Accordion>

  <Accordion title="How do I see what resources my process uses?">
    Use the **See used resources** option from the process contextual menu to view all dependencies including subprocesses, UI templates, data model types, integrations, and more. This helps with impact analysis before making changes and ensures all dependencies are available when exporting or deploying the process.
  </Accordion>
</AccordionGroup>


# Creating a new project
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-project

Learn how to create and configure a new project in FlowX.AI Designer

The first step in building applications with FlowX.AI is creating a project. Projects serve as organized containers containing all the resources needed for your business solutions, including process definitions, UI components, and integrations.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)
</Frame>

## What is a project?

A project in FlowX.AI is a structured container that groups all the resources required to implement a business solution. It's not just a collection of processes - it's a comprehensive unit that manages the entire lifecycle of your app.

<CardGroup>
  <Card title="Centralized Management" icon="folder">
    Manage all resources, processes, and dependencies in one place, reducing context-switching
  </Card>

  <Card title="Version Control" icon="code-branch">
    Track changes with versioning for processes, resources, and configurations
  </Card>

  <Card title="Multi-Environment Deployment" icon="rocket">
    Deploy consistent builds across development, QA, and production environments
  </Card>

  <Card title="Resource Organization" icon="layer-group">
    Ensure clarity with structured resources and reduce configuration errors
  </Card>
</CardGroup>

## Project lifecycle

In FlowX.AI, a project follows a well-defined lifecycle from creation to deployment:

<Steps>
  <Step title="Create Project">
    Define basic project properties and settings
  </Step>

  <Step title="Configure Resources">
    Add and configure all necessary components
  </Step>

  <Step title="Create Version">
    Capture project state at significant milestones
  </Step>

  <Step title="Build Package">
    Create immutable deployment package from a version
  </Step>

  <Step title="Deploy">
    Release to development, QA, or production environments
  </Step>
</Steps>

This documentation covers the first two steps of creating and configuring a new project.

## Creating a project

<Steps>
  <Step title="Access the Projects Section">
    Log in to FlowX.AI Designer and navigate to the **Projects** section from the main navigation.

    <Note>
      You'll need appropriate permissions to create new projects. If you don't see the Projects section, contact your FlowX administrator.
    </Note>
  </Step>

  <Step title="Initiate Project Creation">
    Click the **+ New Project** button to open the project creation dialog.

    <Frame>
      ![Creating a new project](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/create_new_project.gif)
    </Frame>
  </Step>

  <Step title="Define Project Properties">
    Configure the basic properties for your project:

    * **Project Name**: Enter a descriptive name that clearly identifies your business solution
    * **Platform Type**: Select the platform you want to use for your project:
      * Omnichannel
      * Web only
      * Mobile only
  </Step>

  <Step title="Configure Project Settings">
    Set up additional parameters that define how your project will function:

    * **Default Theme**: Choose a theme to apply a consistent look and feel
    * **Number Formatting**:
      * **Min/Max Decimals**: Configure how numbers are displayed
      * **Date Format**: Choose short or long date formats
      * **Currency Format**: Set display as ISO code (USD) or symbol (\$)
    * **Languages**:
      * Set a default language (e.g., English)
      * Add additional languages for localization support

    <Info>
      Project language settings serve two important purposes:

      * They fill the default state for preview in the UI Designer
      * They enable you to create translatable values in enumerations and substitution tags
    </Info>

    <Frame>
      ![Configure initial settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/configure_initial.gif)
    </Frame>
  </Step>
</Steps>

## Configuring project resources

After creating your project, you'll need to configure various resources before you can build and deploy your app. These resources form the foundation of your solution.

<Steps>
  <Step title="Configure Project Resources">
    Your project includes these key resource sections:

    <CardGroup>
      <Card title="Processes" icon="diagram-project">
        Define business processes and subprocesses that orchestrate your application workflows
      </Card>

      <Card title="UI Designer" icon="palette">
        Create application interfaces, components, and screen layouts for your processes
      </Card>

      <Card title="Content Management" icon="newspaper">
        Configure enumerations, substitution tags, and media for consistent content delivery
      </Card>

      <Card title="Task Management" icon="tasks">
        Set up views, stages, and allocation rules for workflow orchestration
      </Card>

      <Card title="Integrations" icon="plug">
        Connect to external systems with API endpoints and workflow configurations
      </Card>

      <Card title="Dependencies" icon="code-branch">
        Add libraries containing reusable resources shared across projects
      </Card>

      <Card title="Resources" icon="images">
        Manage media files, fonts, themes, and other assets used across your app
      </Card>

      <Card title="Configuration" icon="sliders">
        Define environment-specific parameters for deployment flexibility
      </Card>
    </CardGroup>

    <Info>
      **Resource Inventory**: Your project can include the following components:

      **Process Resources**:

      * Process definitions with BPMN diagrams
      * Action configurations and task settings
      * Subprocess definitions and connections

      **UI Resources**:

      * Screen layouts and component configurations
      * Form definitions and validation rules
      * Navigation flows and interaction patterns

      **Content Resources**:

      * Enumerations for dropdown menus and selections
      * Substitution tags for dynamic content
      * Media assets (images, videos, documents)

      **Integration Resources**:

      * API endpoint configurations
      * Data mappings and transformations
      * Workflow definitions for system interactions

      **Supporting Resources**:

      * Themes and styling assets
      * Configuration parameters for environments
      * Library dependencies for shared functionality
    </Info>

    <Tip>
      **Configuration Best Practices**:

      * Begin with process definitions before configuring supporting resources
      * Use clear, consistent naming conventions across all resources
      * Configure reusable components in libraries when they'll be used in multiple projects
      * Test individual components before integrating them into the complete workflow
      * Set up environment variables for settings that differ between environments
      * Create versions after completing significant resource configurations
    </Tip>
  </Step>

  <Step title="Create Process Definitions">
    Process definitions are the core of your application, defining the user journey and business logic:

    * Navigate to the **Processes** section
    * Click **+ New Process** to create a new process
    * Use the BPMN editor to design your process flow
    * Configure actions, forms, and integration points

    <Card title="Learn more about Process Definitions" href="../managing-a-project-flow/creating-a-new-process-definition" icon="link" />
  </Step>

  <Step title="Design User Interfaces">
    Create the screens and components users will interact with:

    * Navigate to the **UI Designer** section
    * Create screens for each user-facing step in your processes
    * Configure forms, buttons, and other interactive elements
    * Design responsive layouts for different device types
  </Step>

  <Step title="Configure Integrations">
    Set up connections to external systems and services:

    * Define API endpoints for backend integrations
    * Configure authentication and security settings
    * Create workflows for complex integration scenarios
    * Test connections to ensure proper data exchange
  </Step>

  <Step title="Set Configuration Parameters">
    Define environment-specific variables:

    * Add parameters that will differ between environments
    * Set default values for development
    * Mask sensitive information like passwords and API keys
    * Organize parameters by functional area

    <Frame>
      ![Configuration Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/config_params.png)
    </Frame>
  </Step>
</Steps>

## Project lifecycle management

After configuring your project resources, you'll need to prepare it for deployment through versioning and building:

<Steps>
  <Step title="Create Project Version">
    When your project configuration reaches a milestone:

    * Create a version to capture the current state
    * You can create multiple versions and commit them before creating a build
    * Versions can be modified until they are committed
    * Committed versions are locked and cannot be changed
  </Step>

  <Step title="Create Build">
    To deploy your project to an environment:

    * Create a build from any committed version
    * Builds are immutable and serve as deployable packages
    * Each build contains exactly one version of a project
    * Once a build is created, its contents (processes, enumerations, substitution tags, integrations) cannot be edited - you'll need to create a new project version for changes

      <Frame>
        <video />
      </Frame>
  </Step>

  <Step title="Deploy Build">
    Deploy your build to the target environment:

    * Development for testing
    * QA for validation
    * Production for end-users

    <Info>
      Configuration parameters set for specific environments will be applied during deployment.
    </Info>
  </Step>
</Steps>

## Best practices

<Warning>
  Projects contain all your process definitions and resources. Use clear naming conventions and proper documentation to maintain organization as your project grows.
</Warning>

* **Project Naming**: Use clear, descriptive names that reflect business purpose
* **Project Scope**: Keep projects focused on specific business domains
* **Documentation**: Add comprehensive descriptions to your project and components
* **Version Control**: Make effective use of the built-in versioning capabilities
* **Configuration Management**: Use environment variables for deployment-specific settings
* **Dependency Management**: Carefully manage library dependencies to avoid conflicts
* **Testing**: Validate changes in development before promoting to production

## Next steps

After creating your project, you can proceed to:

<Card title="Create Process Definition" icon="diagram-project" href="../managing-a-project-flow/creating-a-new-process-definition">
  Define your first business process within the project
</Card>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I create a new version of a project?">
    To create a new version, navigate to the project dashboard, select "Create New Version," and make any changes. Once finalized, commit the version to lock it.
  </Accordion>

  <Accordion title="What happens when I create a build?">
    Creating a build captures a snapshot of the project version, consolidating resources into a single deployable package. Builds are immutable and cannot be edited once created.
  </Accordion>

  <Accordion title="Can I manage multiple localizations within a project?">
    Yes, projects support multiple locales. You can define regional settings, such as date formats and currencies, to cater to different environments.

    <Card title="Learn more about Localization" href="../../building-blocks/ui-designer/localization-and-i18n" icon="page" />
  </Accordion>

  <Accordion title="What is the difference between a Project Version and a Build?">
    A Project Version is a snapshot of resources and configurations that can be modified, tracked, and rolled back. A Build is a deployable package created from a committed version, and it is immutable once deployed.
  </Accordion>

  <Accordion title="How do I add a library as a dependency?">
    Go to your project settings, navigate to dependencies, and select the desired library. Choose the build you want to use, and its resources will be accessible within your project.
  </Accordion>

  <Accordion title="Can I make changes to a deployed build?">
    No, a build is immutable. To make changes, modify the project version, create a new version, and deploy a new build.
  </Accordion>

  <Accordion title="How do I ensure that a library update doesn't break my project?">
    Use a controlled environment like Dev or UAT to test new builds of the library before updating the dependency in your main project. This allows you to validate changes and ensure they don't negatively impact your project.
  </Accordion>

  <Accordion title="What happens to resource versions when I update a dependency?">
    When a dependency is updated to a newer build, any resources that were modified in the library will reflect the latest version. Projects have control over when to update, so older versions remain stable until the dependency is manually updated.
  </Accordion>
</AccordionGroup>


# Creating a User interface
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-user-interface

Learn how to design and configure engaging user interfaces for your process flows using FlowX.AI Designer.

FlowX.AI allows you to create rich, interactive user interfaces for your process flows without extensive coding. Using the UI Designer, you can configure screens with various components and navigation patterns to create intuitive user experiences.

<Frame>
  ![User Interface Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui.png)
</Frame>

## Understanding UI design in FlowX.AI

<Card title="UI Design Concepts" icon="palette">
  In FlowX.AI, user interfaces are primarily associated with **User Task** nodes in your process flow. Each User Task can represent a screen or part of a screen in your app. The UI Designer provides a visual editor where you can add, arrange, and configure UI components to create your desired interface.
</Card>

<CardGroup>
  <Card title="UI Designer Documentation" href="../../building-blocks/ui-designer/ui-designer" icon="file-lines">
    Comprehensive guide to the UI Designer and available components
  </Card>

  <Card title="Navigation Areas" href="../../building-blocks/process/navigation-areas" icon="sitemap">
    Learn more about different navigation patterns and structures
  </Card>
</CardGroup>

## Creating a process with user interfaces

<Steps>
  <Step title="Create a Process Definition">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Go to the **Processes** section and click **+ New Process**
    3. Give your process a descriptive name and click **Create**

    <Tip>
      Plan your user interface flow before starting. Consider how many screens you need and how users will navigate between them.
    </Tip>
  </Step>

  <Step title="Add Process Flow Nodes">
    1. Add a **Start Node** to your process canvas
    2. Add **User Task** nodes for each screen in your application
    3. Connect the nodes in the sequence users will navigate through them
    4. Add an **End Node** to complete your process

    <Frame>
      ![User Interface Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui.png)
    </Frame>

    <Note>
      Each User Task node represents a screen or a significant UI interaction in your application. Design your process flow to match your intended user journey.
    </Note>
  </Step>

  <Step title="Create a Navigation Area">
    1. With your process open in edit mode, click the **Navigation** tab
    2. Click the **+ Add** button to create a new navigation area
    3. Select **Page** as the navigation type (or another type based on your needs)
    4. Name your navigation area (e.g., "Main Application Page")
    5. Assign the relevant User Task nodes to this navigation area

    <Frame>
      ![Create Navigation Area](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui1.gif)
    </Frame>

    <Info>
      **Available Navigation Area Types:**

      * **Stepper**: Breaks progress into logical, numbered steps for intuitive navigation
      * **Tab Bar**: Allows users to switch between different sections or views
      * **Page**: Displays full-page content for an immersive experience
      * **Modal**: Overlays that require user interaction before returning to the main interface
      * **Zone**: Groups specific navigation areas or tasks, like headers and footers
      * **Parent Process Area**: Supports subprocess design under a parent hierarchy
    </Info>
  </Step>
</Steps>

## Configuring the UI

All visual properties of UI elements and navigation areas are configured using the FlowX.AI UI Designer, which provides a visual editor for building your interfaces.

<Frame>
  ![UI Designer Location](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/where_ui1.png)
  ![UI Designer Access](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/where_ui2.png)
</Frame>

### Selecting navigation type

To begin, you need to define the type of navigation for your app:

<Steps>
  <Step title="Configure Navigation Type">
    1. In the UI Designer, go to the navigation configuration section
    2. Select one of the following navigation types:
       * **Single page form**: For simple, one-page applications
       * **Wizard**: For multi-step processes with clear progression

    <Frame>
      ![Navigation Type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui3.png)
    </Frame>

    <Info>
      For this example, we'll use the **Wizard** type, which is ideal for multi-step processes like applications or onboarding flows.
    </Info>
  </Step>
</Steps>

## Designing the first screen

Let's configure the first User Task node to create an engaging and functional screen:

<Steps>
  <Step title="Open the UI Designer">
    1. In your process diagram, select the first **User Task** node
    2. Click the **UI Designer** button in the properties panel
    3. This will open the visual UI Designer for this specific node
  </Step>

  <Step title="Add a Card Component">
    1. From the component palette, drag a **Card** component onto the canvas
    2. The Card component will serve as a container for your form elements
    3. Configure the card's appearance using the properties panel (size, padding, etc.)
  </Step>

  <Step title="Add a Form Component">
    1. Drag a **Form** component into the Card
    2. Forms help organize inputs and handle data binding
    3. Configure the form's properties as needed
  </Step>

  <Step title="Add Input Fields">
    1. Drag an **Input** component into the Form
    2. Configure the input's properties:
       * Set a label (e.g., "Full Name")
       * Choose the input type (text, number, email, etc.)
       * Configure validation rules if needed
       * Set the data binding to store user input

    <Frame>
      ![First Card UI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_card1.png)
    </Frame>
  </Step>

  <Step title="Add a Button with Action">
    1. Drag a **Button** component into the Form
    2. Configure the button text (e.g., "Continue" or "Next")
    3. Set up the button's action to trigger process advancement

    <Info>
      Before the button will work, you need to configure an action on the User Task node itself. This action will be triggered when the button is clicked.
    </Info>

    <Frame>
      ![Save Data Action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui_save_data.png)
    </Frame>
  </Step>
</Steps>

### Testing the first screen

<Steps>
  <Step title="Preview Your Screen">
    1. Save your UI design
    2. Start the process to test the UI
    3. The Card with the Form and Input field should be displayed as configured

    <Frame>
      ![Test First Screen](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/test_card_ui.gif)
    </Frame>
  </Step>
</Steps>

## Designing the second screen

Follow a similar process to design your second screen:

<Steps>
  <Step title="Configure the Second User Task">
    1. Select the second **User Task** node in your process
    2. Open the **UI Designer**
    3. Add a **Card** component
    4. Add other UI components as needed (text, inputs, buttons, etc.)

    <Frame>
      ![Second Card UI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui4.png)
    </Frame>
  </Step>

  <Step title="Add Navigation Actions">
    1. Add a button to submit the form or continue to the next step
    2. Configure actions on the User Task node as needed
    3. Consider adding a "Back" button if appropriate for your flow
  </Step>
</Steps>

## Testing the complete flow

Once you've configured all your screens, test the complete process flow:

<Frame>
  ![Test Complete Flow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/final_rez.gif)
</Frame>

## Available UI components

FlowX.AI provides a rich set of UI components to create engaging interfaces:

<CardGroup>
  <Card title="Layout Components" icon="table-columns">
    Cards, containers and grids for organizing content
  </Card>

  <Card title="Form Elements" icon="input-text">
    Inputs, checkboxes, radio buttons, selects, switches, sliders, segmented buttons and date pickers
  </Card>

  <Card title="Interactive Elements" icon="hand-pointer">
    Buttons, links, tabs, and accordions for user interaction
  </Card>

  <Card title="Content Components" icon="font">
    Text, images, icons, and media elements for displaying information
  </Card>

  <Card title="Data Display" icon="table">
    Tables for showing structured data
  </Card>

  <Card title="Navigation" icon="compass">
    Steppers, and pagination controls
  </Card>

  <Card title="Other" icon="ellipsis">
    Other components for building complex interfaces
  </Card>
</CardGroup>

## Best practices

<Tip>
  **When designing user interfaces:**

  * **Use consistent styling** across all screens for a cohesive user experience
  * **Group related inputs** within logical sections or cards
  * **Implement proper validation** to prevent errors and guide users
  * **Provide clear feedback** on actions with success and error messages
  * **Design with [accessibility](../../platform-deep-dive/accessibility)** in mind using proper labels and ARIA attributes
  * **Test your UI** on different screen sizes to ensure responsive design
  * **Keep navigation intuitive** with clear paths forward and back
  * **Use data binding** to maintain state across screens
</Tip>

## Next steps

After creating your user interface, you can:

<Card title="Moving a token backwards in the flow" icon="arrow-left" href="../managing-a-project-flow/moving-a-token-backwards-in-a-process">
  Learn how to move a token backwards in the flow
</Card>


# Exporting and importing projects
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition

Learn how to transfer projects between environments using the export and import functionality in FlowX.AI Designer.

Moving projects between environments is a common requirement in enterprise software development. FlowX.AI provides export and import functionality to help you promote your projects from development to testing and production environments.

<Info>
  In recent versions of FlowX.AI, the export/import functionality has moved from the process definition level to the project level, allowing for more comprehensive and consistent transfers between environments.
</Info>

<Note>
  Export and import are driven from the **Designer UI**. There is no public REST API to import a process definition or project programmatically — drive the workflow through the Designer.
</Note>

## Project vs. process export/import

<Card title="Project-Level Operations" icon="folder-tree">
  Modern versions of FlowX.AI use **project-level** export and import operations rather than process-level ones. This approach ensures that all related resources, dependencies, and configurations are transferred together, maintaining the integrity of your application.
</Card>

<Note>
  This documentation covers the updated project export/import approach. If you're using an older version of FlowX.AI that still handles exports at the process definition level, some details may differ.
</Note>

## Exporting a project

You can export projects from the version details panel. This allows you to export specific committed versions with granular control over what's included in the export.

<Steps>
  <Step title="Navigate to Version Details">
    1. Open **FlowX.AI Designer** and go to the **Projects** section
    2. Select the project you want to export
    3. Navigate to the version details panel for the specific committed version you want to export
  </Step>

  <Step title="Initiate Export">
    1. In the version details panel, locate the **Export Version** button
    2. Click **Export Version** to start the export process

    <Frame>
      ![Export Version Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/export_version.png)
    </Frame>
  </Step>

  <Step title="Configure Binary Files Option">
    When exporting, a modal appears asking whether to include binary files:

    * **Include**: Includes binary files (for example, images, documents, media assets) in the export. This may increase the export file size and the time required to import the version in another environment.
    * **Don't include**: Exports only the project structure and configurations without binary files. This results in a smaller export file and faster import times.

    <Warning>
      Including binary files may significantly increase the export file size and the time required to import the version in another environment. Only include binary files if they are necessary for the target environment.
    </Warning>

    <Frame>
      ![Include Binary Files modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/include_binary_files.png)
    </Frame>
  </Step>

  <Step title="Complete the Export">
    1. Select your preferred binary files option
    2. Click **Continue** to proceed with the export
    3. The system will generate a downloadable file containing your project version
    4. Save this file to your local system

    <Tip>
      Use a clear naming convention for your export files to help identify their contents later, such as `[project-name]_[version]_[environment]_[date].zip`.
    </Tip>
  </Step>
</Steps>

<Info>
  For more information about versioning and managing project versions, see the [Versioning documentation](../../projects/managing-applications/versioning#exporting-versions).
</Info>

### Exporting builds

You can also export builds directly from the **Builds** section. This is useful when you want to transfer a specific build (rather than a version) between environments.

<Steps>
  <Step title="Navigate to Builds Section">
    1. Open **FlowX.AI Designer** and go to the **Projects** section
    2. Select your project and navigate to **Runtime** and then to the **Builds** section
  </Step>

  <Step title="Select Build to Export">
    1. Locate the build you want to export in the builds list
    2. Click the **Export** icon (box with upward arrow) for the desired build
  </Step>

  <Step title="Complete Export">
    The build export follows the same process as version export, including the binary files option. The exported build can be imported into other environments or workspaces.
  </Step>
</Steps>

<Info>
  Builds are immutable snapshots of committed project versions. When exporting a build, you're exporting a deployable package that can be directly used in runtime environments. For more information about builds, see the [Builds documentation](../../projects/runtime/builds).
</Info>

## Importing a project

<Steps>
  <Step title="Open the Projects section">
    Open **FlowX.AI Designer** in the target environment and go to the **Projects** section.
  </Step>

  <Step title="Open the Import menu">
    Click the three-dots (kebab) menu at the top right of the Projects list and choose one of:

    * **Import Version** — restores a project version (and its full version history) into the target environment. Use this when promoting work between environments.
    * **Import Build** — imports a build (an immutable snapshot of a committed version) into the **Builds** section. Use this when promoting a deployable package.

    The menu only shows the items you have permission for.

    <Tip>
      You can also start an **Import Version** from inside an open project: open the **All Branches** view in the Version Details panel and click the upload icon in the panel header. This is functionally equivalent to **Import Version** from the Projects list.
    </Tip>
  </Step>

  <Step title="Select the .zip file">
    The Designer opens your operating system's file chooser. Select the `.zip` you exported earlier and confirm.
  </Step>

  <Step title="Wait for the import to complete">
    The import runs asynchronously. A toast notification confirms success or reports an error. There is no in-app preview, no confirmation dialog, and no manual conflict-resolution step between picking the file and the import completing — see [Import scenarios](#import-scenarios) below for what happens when the target environment already has the project.
  </Step>
</Steps>

<Warning>
  If the target environment has versions on the same lineage as the import file, those versions are silently stashed during the import. There is no preview or confirmation step before this happens. See [Existing project with additional versions](#existing-project-with-additional-versions) for the consequences and the recommended workflow.
</Warning>

## Import scenarios

When importing a project, you may encounter different scenarios depending on whether the project already exists in the target environment and what versions are present.

### New project import

<Card title="New project" icon="plus">
  If the project does not exist in the target environment, it will be created with all its resources, and you'll see all versions from the export file.
</Card>

### Existing project with no additional versions

<Card title="Update Existing Project" icon="arrows-rotate">
  If the project exists but doesn't have versions beyond those in the import file, the system will update the existing project with any changes from the import file.
</Card>

### Existing project with additional versions

Importing restores the version history and parent–child relationships exactly as they exist in the import file. **There is no merge functionality on import.**

<Card title="Versions become stashed, not merged" icon="triangle-exclamation">
  If the target environment has versions on the same lineage that are not in the import file, those versions become **stashed**: they remain in the database but are no longer accessible in the Designer. There is no UI to retrieve stashed versions — recovery requires direct database intervention by FlowX support and is not always feasible.
</Card>

<Warning>
  **Importing on top of diverged work is destructive.** If two environments committed different versions on the same branch, importing one over the other stashes the target version. The previous content cannot be restored from the Designer. Always export the target project before importing on top of it, and contact FlowX support if recovery is needed.
</Warning>

<Tip>
  **Recommended workflow:** Use a separate branch per environment. On import, new branches are added alongside existing ones instead of overwriting versions on a shared lineage.
</Tip>

### Cross-workspace import

You can import the same project into multiple workspaces on the same environment. This removes the previous limitation that restricted a project (identified by its UUID) to exist in only one workspace per environment.

<Card title="Cross-Workspace Import" icon="layer-group">
  Import a project build (and optionally a version) into a different workspace on the same environment. The imported project maintains its own independent lifecycle with separate active policies and access controls.
</Card>

**Key behaviors for cross-workspace import:**

| Aspect                    | Behavior                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Lifecycle**             | The imported project has its own independent lifecycle in the new workspace                                                      |
| **Active Policy**         | The imported build is automatically set as the active policy, regardless of what was active in the original workspace            |
| **Access Controls**       | Separate access controls and policies are defined for each workspace                                                             |
| **No Impact on Original** | The import does not affect the original project's settings, policies, or process instances                                       |
| **User Access**           | Workspace users must be granted appropriate project rights (for example, project viewer) to interact with the imported project   |
| **Process Instances**     | Process instances are workspace-specific; the imported project starts with no instances until processes run in the new workspace |
| **Database**              | Projects across workspaces on the same environment share the same database                                                       |

<Tip>
  **Use case**: Use this feature to represent different operational environments (UAT, Staging, Pre-production) as separate workspaces on a single FlowX deployment, reducing infrastructure and DevOps costs.
</Tip>

<Card title="Workspaces documentation" href="../../projects/workspaces#cross-workspace-project-import" icon="building-columns">
  Learn more about cross-workspace project management
</Card>

***

## Cross-version export and import

<Info>
  **Available starting with FlowX.AI 5.9.0**

  Environments are not always on the same platform version. During a phased upgrade, lower environments (dev, test) are usually upgraded first, while upper environments (staging, production) stay on the previous version until the upgrade is validated and scheduled. Cross-version compatibility lets you export a project version or build from a higher platform version in a format that an environment running a **lower** platform version can import — so you can still ship fixes to an environment that hasn't been upgraded yet.
</Info>

When a problem is found in an upper environment during an upgrade window, the source-of-truth project version often already lives on an upgraded environment. Cross-version export and import lets you deliver the fix to the older environment without rolling back the upgrade on lower environments or rushing the upgrade of the upper ones.

A newer platform version can always import exports produced by an older one. The case that needs handling is the reverse — exporting from a newer version so an older one can import it — which is what this section covers.

Cross-version compatibility is supported **between LTS lines** — currently the **5.1.x** and **5.9.x** LTS lines. It is patch-agnostic: an export produced on any 5.9.x patch release is compatible with any 5.1.x patch release.

### When to use it

Use cross-version export and import when **all** of the following are true:

* Lower environments (for example, dev and test) have already been upgraded to a newer platform version.
* One or more upper environments (for example, staging or production) are still on an older platform version.
* A fix or change must be delivered to an upper environment before it is upgraded.

### How incompatible content is handled

A cross-version export works only when the exported content stays within what the **target (lower) platform version** can understand. When you export targeting an older version, resources whose type doesn't exist on that version are handled automatically:

* **Incompatible resources are excluded** from the export and from the manifest, rather than failing the export.
* **Resources that reference an excluded resource are still exported.** Their usages are kept as-is and point to the now-missing resource; references are not removed and dependents are not cascade-excluded.
* **The excluded resources are listed** in a separate `manifest_excluded.json` file in the archive. Kept resources stay in `manifest.json`. The excluded-list file is informational only and is ignored on import.
* **The export still imports successfully** into the older environment.

<Warning>
  Keep the fix on the upgraded environment limited to functionality that also exists on the older target version. Resource types, properties, or behaviors introduced after the target version cannot be carried over — they are excluded from the export and must wait until the target environment itself is upgraded.

  As a rule of thumb, the **lowest** platform version in the export/import path defines the set of functionality usable for that fix. As long as the fix uses only features available on the target version, the round trip is lossless.
</Warning>

### Example: hotfix to production on an older version

Consider a phased upgrade where the lower environments are already on 5.9 but production is still on 5.1:

| Environment | Platform version |
| ----------- | ---------------- |
| dev         | 5.9              |
| uat         | 5.9              |
| production  | 5.1              |

A defect is reported in production (still on 5.1) and must be fixed before production is upgraded. The source-of-truth project version now lives on the upgraded dev/uat environments.

<Steps>
  <Step title="Apply the fix on the upgraded environment">
    Make the change in the project version on dev/uat (5.9), keeping it strictly within functionality that also exists on 5.1 — no resources, nodes, actions, or fields introduced after 5.1.
  </Step>

  <Step title="Validate the fix">
    Test the change on the upgraded environment as usual.
  </Step>

  <Step title="Export targeting the lower version">
    Export the project version or build targeting 5.1 so the artifact is produced in a format the 5.1 runtime can import. Anything incompatible with 5.1 is excluded and listed in `manifest_excluded.json`, so you can review or rework it before proceeding.
  </Step>

  <Step title="Import into production">
    Import the compatible artifact into the 5.1 production environment. The fix is applied without upgrading production or rolling back the upgrade on dev/uat.
  </Step>
</Steps>

Provided the fix uses only functionality available in 5.1, no information is lost in the round trip. Anything that depends on post-5.1 functionality cannot be carried over and must wait until production is upgraded.

### Limitations

* A cross-version export is only as capable as the **target** version. Newer functionality cannot be downgraded into an older runtime.
* This mechanism delivers fixes to a not-yet-upgraded environment during an upgrade window. It is not a substitute for upgrading the upper environments.
* Always validate the imported build on the target environment, since the fix was authored and tested on a different platform version.

***

## Best practices for export/import

<Tip>
  **When transferring projects between environments:**

  * **Plan your promotion path** - Establish a clear workflow for moving from development to testing to production
  * **Use consistent naming** - Name your projects, versions, and export files consistently across environments
  * **Document dependencies** - Keep track of dependencies between projects and libraries
  * **Test after import** - Always validate your project in the new environment after import
  * **Version control** - Consider using external version control systems in addition to FlowX.AI's built-in versioning
  * **Incremental imports** - For large projects, consider importing incrementally rather than all at once
  * **Export the target project before importing** - Importing on top of diverged work stashes the target version, and stashed versions cannot be recovered from the Designer. Exporting the target first gives you a recovery point.
</Tip>

## Common issues and solutions

<AccordionGroup>
  <Accordion title="Version Compatibility">
    **Issue**: An export from a newer environment contains resources that the older target environment does not support.

    **Solution**: A cross-version export to an older platform version automatically excludes resources that the target version can't interpret and records them in a separate excluded-resources file inside the archive. The export imports successfully; review the excluded list and adjust any resources that referenced them. See [Cross-version export and import](#cross-version-export-and-import).
  </Accordion>

  <Accordion title="Missing Dependencies">
    **Issue**: Imported project references libraries or resources not present in the target environment.

    **Solution**: Export and import dependencies first, or update the project to use dependencies available in the target environment.
  </Accordion>

  <Accordion title="Conflict Resolution">
    **Issue**: Conflicts between imported versions and existing versions.

    **Solution**: Carefully review the differences and decide whether to overwrite or preserve existing versions. Consider merging changes manually for complex conflicts.
  </Accordion>

  <Accordion title="Environment-Specific Configurations">
    **Issue**: Hard-coded environment-specific values in processes or configurations.

    **Solution**: Use environment variables and configuration parameters instead of hard-coded values to ease transitions between environments.
  </Accordion>
</AccordionGroup>

## Next steps

After importing your project, you should:

<CardGroup>
  <Card title="Verify Project Resources" icon="check">
    Ensure all process definitions, UI components, and other resources imported correctly
  </Card>

  <Card title="Configure Environment Settings" icon="sliders">
    Adjust any environment-specific settings for the new environment
  </Card>

  <Card title="Test Process Flows" icon="vial">
    Validate that all process flows work as expected in the new environment
  </Card>

  <Card title="Create a Build" icon="box">
    Create a build from your imported project for deployment
  </Card>
</CardGroup>


# Handling decisions in the flow
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/handling-decisions-in-the-flow

Learn how to implement conditional branching in your processes using exclusive gateways to create dynamic, decision-driven workflows.

Business processes often require making decisions based on data and conditions. FlowX.AI's exclusive gateway nodes allow you to create branching paths in your process flow, directing the execution based on specific conditions and business rules.

<Frame>
  ![Exclusive Gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_exclusive.png#center)
</Frame>

## What is an exclusive gateway?

<Card title="Exclusive Gateway" icon="diamond">
  An exclusive gateway (also known as an XOR gateway) creates conditional branches in your process flow. It directs the process token to exactly one of the outgoing paths based on evaluated conditions. Think of it as an "if-then-else" decision point in your process.
</Card>

<CardGroup>
  <Card title="Exclusive Gateway Documentation" href="../../building-blocks/node/exclusive-gateway-node" icon="file-lines">
    Complete reference for exclusive gateway configuration
  </Card>

  <Card title="Business Rules" href="../../building-blocks/actions/business-rule-action/business-rule-action" icon="code">
    Learn more about implementing decision logic
  </Card>
</CardGroup>

## How exclusive gateways work

<Frame>
  ![Exclusive Gateway Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/xclsv_mapf.png)
</Frame>

Exclusive gateways function as decision points in your process:

1. When the process flow reaches an exclusive gateway, it evaluates conditions associated with each outgoing path
2. The first condition that evaluates to `true` determines which path is taken
3. Only one path is followed, even if multiple conditions could evaluate to `true`
4. A default path can be specified to be taken if no conditions are met

<Info>
  Best practice is to always provide a default path to ensure your process doesn't get stuck if none of the specified conditions are met.
</Info>

## Creating a flow with exclusive branches

<Steps>
  <Step title="Create or Open a Process Definition">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Go to the **Processes** section and select your process or create a new one
    3. Click the **Edit Process** button to open the Process Designer
  </Step>

  <Step title="Add Basic Flow Elements">
    1. Add a **Start Node** to your process canvas (if creating a new process)
    2. Add a node before your decision point (typically a task or user task node)
    3. Ensure the necessary data for your decision is available in the process at this point

    <Tip>
      The decision conditions will evaluate data that's already in your process context, so make sure any required data is collected or calculated before reaching the gateway.
    </Tip>
  </Step>

  <Step title="Add the Decision Gateway">
    1. From the node palette, drag an **Exclusive Gateway** node onto your canvas
    2. Connect your previous node to this gateway
    3. Give your gateway a descriptive name that indicates its decision purpose (e.g., "Evaluate Credit Score")

    <Warning>
      You must connect all outgoing paths from the exclusive gateway before configuring the decision conditions.
    </Warning>
  </Step>

  <Step title="Create Outgoing Paths">
    1. Add the task nodes that will be the targets for each decision branch
    2. Connect the exclusive gateway to each of these nodes using sequence flows
    3. Name each sequence flow to indicate the condition (e.g., "Premium Card Path", "Standard Card Path")

    <Frame>
      ![Gateway Condition Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_gateway_condition.png)
    </Frame>
  </Step>

  <Step title="Configure Decision Conditions">
    1. Select one of the sequence flows (arrows) from the gateway
    2. In the properties panel, navigate to the **Condition** section
    3. Select a **scripting language** from the dropdown (e.g., MVEL, JavaScript)
    4. Enter your condition expression, for example:

    ```javascript theme={"system"}
    input.get("application.client.creditScore") >= 700
    ```

    5. Repeat for each outgoing path with the appropriate condition:

    ```javascript theme={"system"}
    input.get("application.client.creditScore") < 700
    ```

    <Info>
      Conditions are evaluated in the order they appear in the Designer. The first condition that evaluates to `true` determines the path taken, so order matters!
    </Info>
  </Step>

  <Step title="Add Converging Gateway (Optional)">
    If your branches need to converge back to a single flow:

    1. Add another **Exclusive Gateway** after your branch tasks
    2. Connect each branch endpoint to this converging gateway
    3. Continue the process flow from this gateway

    <Note>
      A converging exclusive gateway doesn't require conditions since it's merely joining paths rather than splitting them.
    </Note>
  </Step>

  <Step title="Complete the Process Flow">
    1. Add any additional nodes needed after the decision branches
    2. Ensure your process eventually reaches an **End Node**
    3. Save your process definition
  </Step>
</Steps>

## Condition expression examples

Here are some example condition expressions for different decision scenarios:

<AccordionGroup>
  <Accordion title="Numeric Comparisons">
    ```javascript theme={"system"}
    // Check if age is over 18
    input.get("customer.age") >= 18

    // Check if balance is sufficient
    input.get("account.balance") > input.get("transaction.amount")

    // Check if score is within a range
    input.get("application.score") >= 600 && input.get("application.score") < 750
    ```
  </Accordion>

  <Accordion title="String Comparisons">
    ```javascript theme={"system"}
    // Check customer type
    input.get("customer.type") == "premium"

    // Check if country is in EU
    ["DE", "FR", "IT", "ES"].contains(input.get("customer.country"))

    // Check if name starts with specific letters
    input.get("customer.lastName").startsWith("A")
    ```
  </Accordion>

  <Accordion title="Boolean logic">
    ```javascript theme={"system"}
    // Check multiple conditions with AND
    input.get("customer.verified") == true && input.get("customer.active") == true

    // Check multiple conditions with OR
    input.get("application.status") == "pending" || input.get("application.status") == "review"

    // Complex condition with nested logic
    (input.get("customer.age") >= 21 || (input.get("customer.age") >= 18 && input.get("customer.parentalConsent") == true)) && input.get("customer.verified") == true
    ```
  </Accordion>

  <Accordion title="Date Comparisons">
    ```javascript theme={"system"}
    // Check if membership is expired
    new java.text.SimpleDateFormat("yyyy-MM-dd").parse(input.get("membership.expiryDate")).before(new java.util.Date())

    // Check if account is older than 1 year
    dateDiffInDays(new java.text.SimpleDateFormat("yyyy-MM-dd").parse(input.get("account.openDate")), new java.util.Date()) > 365
    ```
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  **When implementing decision logic:**

  * **Use clear, descriptive names** for gateways and sequence flows to document the decision logic
  * **Keep conditions simple and focused** on a single aspect of the decision
  * **Ensure conditions are mutually exclusive** when possible to avoid ambiguity
  * **Always provide a default path** to handle unexpected scenarios
  * **Test each decision branch** with various input data to verify correct routing
  * **Document complex decision logic** in the process documentation or node descriptions
  * **Consider using business rule actions** before the gateway for complex evaluations
</Tip>

## Common patterns

<CardGroup>
  <Card title="If-Then-Else" icon="code-branch">
    The simplest decision pattern with two outcomes - a condition is either met or not met
  </Card>

  <Card title="Multi-Choice" icon="diagram-project">
    Multiple conditions evaluated in sequence, with one path chosen based on the first match
  </Card>

  <Card title="Approval Flow" icon="check-to-slot">
    Branching based on approval status, typically with approve/reject/review paths
  </Card>

  <Card title="Eligibility Check" icon="clipboard-check">
    Evaluation of multiple criteria to determine if a process can proceed
  </Card>
</CardGroup>

## Next steps

After implementing decision logic in your process, you can:

<Card title="Implement Parallel Processing" icon="network-wired" href="../managing-a-project-flow/adding-more-flow-branches">
  Learn how to create parallel process branches with parallel gateways
</Card>


# Moving a token backwards in a process
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process

Learn how to implement "Back" functionality in your processes to allow users to return to previous steps while preserving data.

While most process flows progress in a forward direction, FlowX.AI provides capabilities for moving backwards in a process flow. This feature allows users to revisit previous steps without losing their progress or data, enhancing the flexibility and user-friendliness of your apps.

<Frame>
  ![Back Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/allow_back_action.png)
</Frame>

## What is token resetting?

<Card title="Token Concept" icon="location-dot">
  In FlowX.AI, a **token** represents the current position within a process instance. It moves from one node to another as the process executes, carrying process data and state information. Normally, tokens advance forward through the process flow, but sometimes you need to allow users to go back to previous steps.
</Card>

<CardGroup>
  <Card title="Process Tokens" href="../../building-blocks/token" icon="file-lines">
    Learn more about tokens and how they drive process flow
  </Card>

  <Card title="Process Instances" href="../../projects/runtime/active-process/process-instance" icon="diagram-project">
    Understand how processes execute in FlowX.AI
  </Card>
</CardGroup>

## Why use backwards navigation?

<CardGroup>
  <Card title="User Experience" icon="user">
    Allows users to correct mistakes or review previous inputs without starting over
  </Card>

  <Card title="Process Flexibility" icon="arrows-up-down-left-right">
    Creates more natural and less rigid process flows that adapt to user needs
  </Card>

  <Card title="Data Preservation" icon="database">
    Maintains important data while allowing selective changes to specific fields
  </Card>

  <Card title="Reduced Abandonment" icon="chart-line">
    Decreases process abandonment rates by allowing users to navigate freely
  </Card>
</CardGroup>

## How token resetting works

When a user navigates backwards in a process:

1. The current token is marked as **aborted**
2. A **new token** is created at the target node (the previous step)
3. Data is selectively copied from the original token to the new one
4. Any subprocesses started between the original and new positions are aborted
5. The process continues from the reset position with the new token

<Info>
  The token can only be reset to specific actions on specific nodes that have been configured to allow backwards navigation.
</Info>

## Configuring backwards navigation

<Steps>
  <Step title="Identify Target Nodes">
    First, determine which nodes in your process should allow users to navigate back to them. Typically, these are:

    * Key decision points
    * Form submission steps
    * Points where users might need to correct previous inputs
    * The beginning of logical sections in your process
  </Step>

  <Step title="Configure Node Actions">
    1. Select the node that should be a target for backwards navigation
    2. Add or edit an action on this node
    3. In the action configuration, enable the **Allow BACK on this action?** option

    <Frame>
      ![Back Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/allow_back_action.png)
    </Frame>

    <Warning>
      Only configure "back" functionality on actions that make logical sense as return points in your process. Too many back points can make process state management complex.
    </Warning>
  </Step>

  <Step title="Configure Data Handling">
    When a token is reset, you need to decide which data to retain and which to discard. Configure this using:

    1. **Remove the following objects from current state**: Specify process keys that should be deleted when navigating back to this action
    2. **Copy the following objects from current state**: Specify process keys that should retain their data from before the navigation

    <Tip>
      Carefully consider which data to preserve. Generally, you want to keep contextual or reference data while allowing changes to the specific data related to the step being revisited.
    </Tip>
  </Step>

  <Step title="Implement UI Navigation">
    Add navigation controls in your user interface:

    1. Add a "Back" button to relevant screens
    2. Configure the button to trigger the action with back functionality
    3. Ensure the UI updates appropriately when the user navigates back

    <Frame>
      ![Token Reset Animation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/pf_moving_token_bw.gif)
    </Frame>
  </Step>
</Steps>

## Use cases for backwards navigation

<AccordionGroup>
  <Accordion title="Multi-Step Forms">
    In applications with multi-step forms or wizards, backwards navigation allows users to review and edit their inputs across different steps before final submission.
  </Accordion>

  <Accordion title="Decision Correction">
    When users make selections that lead down specific process paths, back functionality lets them change their mind and explore alternative options.
  </Accordion>

  <Accordion title="Error Correction">
    If validation occurs after a form submission and errors are found, users can navigate back to fix issues while preserving other valid inputs.
  </Accordion>

  <Accordion title="Process Review">
    In complex workflows like loan applications or onboarding processes, users often need to review previous sections before completing the process.
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  **When implementing backwards navigation:**

  * **Be selective** about which nodes allow back functionality
  * **Consider data dependencies** between steps to avoid inconsistent states
  * **Provide clear UI indicators** for steps users can navigate back to
  * **Test thoroughly** to ensure data is properly preserved or reset
  * **Consider subprocess implications** as they will be aborted during reset
  * **Document back navigation points** for easier maintenance
  * **Use intuitive button labeling** ("Back", "Previous Step", etc.)
</Tip>

## Technical considerations

<Warning>
  **Keep in mind these technical aspects when implementing back functionality:**

  1. **Performance Impact**: Token resetting involves creating new tokens and copying data, which may impact performance in complex processes
  2. **Subprocess Handling**: Any subprocesses active between the current and target positions will be aborted
  3. **Data Consistency**: Ensure your data model can handle partial updates without creating inconsistencies
  4. **Action Sequencing**: Consider the order of actions that might be re-executed after navigating back
</Warning>


# Initiating/starting processes
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/starting-a-process

Learn the different methods for starting process instances in FlowX.AI, including user interaction, automated triggers, and system integration options.

Once you've designed your process definitions, you'll need to know how to start process instances. FlowX.AI provides multiple ways to initiate processes, from manual user-triggered starts to fully automated system-initiated flows.

<CardGroup>
  <Card title="User Interface" icon="hand-pointer">
    The most common way to start processes through user interaction
  </Card>

  <Card title="Kafka Messages" icon="message">
    Start processes through Kafka events from other systems
  </Card>

  <Card title="Timer Events" icon="clock">
    Schedule processes to start automatically at specific times
  </Card>

  <Card title="Message Events" icon="envelope">
    Trigger processes through message events from other processes
  </Card>
</CardGroup>

## Starting a process via user interface

<Warning>Manual Start using start parameters (JSON data) are limited to 1MB</Warning>

When starting a process manually via the **FlowX Designer UI**, you’ll be prompted to enter a JSON payload (in the "JSON Object" editor). This is subject to the same infrastructure limits as any other process start.

* Payloads must be **under 1MB** total
* If exceeded, the request will fail with:

  ```http theme={"system"}
  413 Content Too Large
  ```

<Frame> ![Start Process Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_params.png) </Frame>

### Affected layers

| Layer                  | Limit                                   | Notes                               |
| ---------------------- | --------------------------------------- | ----------------------------------- |
| NGINX/Ingress          | 1MB (default if not configured)         | `client_max_body_size`              |
| Kafka → Runtime bridge | \~1MB total (default if not configured) | Applies when starting via Kafka too |

### Tips

For larger inputs, consider (as last resort, not recommended) increasing the limits for the affected layers.

## Starting a process via Kafka

One of the most effective ways to initiate processes is through Kafka messaging, which allows systems to communicate and trigger processes without direct user interaction.

<Steps>
  <Step title="Access Your Project">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Select an existing process definition or create a new one that will send the Kafka message
  </Step>

  <Step title="Add a Send Message Task">
    1. Add a **Send Message Task** node to your process flow
    2. Attach a **Kafka Send Action** to this node

    <Tip>
      This task will send the message that initiates another process. You can place it at any appropriate point in your process flow.
    </Tip>
  </Step>

  <Step title="Configure the Kafka Topic">
    1. In the Kafka Send Action configuration, specify the topic linked to the `KAFKA_TOPIC_PROCESS_START_BY_NAME` environment variable
    2. This variable is shared between the **application-manager** and **runtime-manager** deployments

    <Frame>
      ![Process Start Topic Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_process_by_name_topic.png)
    </Frame>

    <Info>
      To verify the topic in FlowX Designer, navigate to: **Platform status → FlowX Components → application-manager-mngt -> kafkaTopicHealthCheckIndicator → details → configuration → topic → process → start-by-name**

      <Frame>
        ![Topic Verification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/topic_kafka.png)
      </Frame>
    </Info>
  </Step>

  <Step title="Add Message Content">
    Add any required data in the message body that should be passed to the new process:

    ```json theme={"system"}
    {"test": "something"}
    ```

    <Note>
      This data will be available to the process being started, providing it with initial context or parameters.
    </Note>
  </Step>

  <Step title="Respect Payload Size Limits">
    <Alert type="warning" title="Payload Size Must Be Under 1MB">
      All Kafka-triggered process starts go through the runtime HTTP API, which enforces strict 1MB payload limits.
    </Alert>

    #### What does this mean?

    * The `variables` field in the Kafka message **must not exceed 1MB**
    * This includes base64 or pretty-printed formats

    #### Why?

    These limits are enforced across:

    | Layer                      | Limit       | Description                            |
    | -------------------------- | ----------- | -------------------------------------- |
    | NGINX/Ingress              | 1MB         | `client_max_body_size`                 |
    | Runtime Manager (Undertow) | 1MB         | `max-http-post-size`                   |
    | Kafka Process Start        | \~1MB total | Translates into a REST call internally |

    #### Recommendations:

    * If absolutely required, increase `max-http-post-size` via:

    ```yaml theme={"system"}
    server:
      undertow:
        max-http-post-size: 2MB
    ```
  </Step>

  <Step title="Configure Required Headers">
    1. Expand the **Advanced Configuration** section
    2. In the headers section, add these required headers:
       * `Fx-Organization-Id`: Organization UUID for the target deployment
       * `Fx-Workspace-Id`: The UUID of the workspace where the process should run
       * `Fx-AppId`: The ID of the project (application) where the process resides
       * `Fx-ProcessName`: The name of the process you want to start
       * `jwt`: Your JWT token for authentication

    <Frame>
      ![Headers Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_process_by_name_headers.png)
    </Frame>

    The headers should look something like this:

    ```json theme={"system"}
    {
      "Fx-Organization-Id": "26ef7b5f-b463-4375-88c8-aaaaaaaaaaaa",
      "Fx-Workspace-Id": "00000000-0000-0000-0000-000000000001",
      "Fx-AppId": "afcc6452-f50e-4d95-ae3b-6b35caed68bd",
      "Fx-ProcessName": "test_kafka",
      "jwt": "your_jwt"
    }
    ```

    <Tip>
      **Don't know where to find these values?** Check the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for step-by-step instructions on locating Application IDs, Process Names, JWT tokens, and more.
    </Tip>

    <Warning>
      Messages missing `Fx-Organization-Id` are rejected immediately with a non-retryable `MissingKafkaHeaderException`. Without an active policy and proper authentication, the process may not start even if the Kafka message is otherwise correctly configured.
    </Warning>
  </Step>

  <Step title="Test and Monitor">
    1. Run your process to send the Kafka message
    2. To monitor the results, you can use tools like AKHQ to check the response on the `KAFKA_TOPIC_PROCESS_START_BY_NAME_OUT` topic

    <Frame>
      ![Kafka Response Monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-11%20at%2017.33.58.png)
    </Frame>
  </Step>
</Steps>

## Timer start event

Timer Start Events allow you to schedule processes to start automatically at defined times or intervals, enabling automated workflows without manual intervention.

<Steps>
  <Step title="Configure a Process with Timer Start">
    1. Open **FlowX.AI Designer** and navigate to your project
    2. Select an existing process definition or create a new one
    3. Add a **Start Timer Event** to your process instead of a regular Start node

    <Frame>
      ![Timer Start Event Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_timer_process.png)
    </Frame>
  </Step>

  <Step title="Configure Timer Settings">
    Configure the timer according to your requirements:

    1. **Date Specific**: Set a specific date and time for the process to start
    2. **Cycle**: Configure a recurring schedule using cron expressions

    <Warning>
      Starting processes through registered timers requires sending a process start message to Kafka, which needs a service account and authentication. See [Service Accounts](../../../setup-guides/access-management/configuring-an-iam-solution#scheduler-service-account) for details.
    </Warning>
  </Step>
</Steps>

For more detailed information about Timer Start Events, refer to the [Start Timer Event](../../building-blocks/node/timer-events/timer-start-event) documentation.

## Message catch start event

Message Catch Start Events allow one process to initiate another through message-based communication, creating dependencies and workflows between processes.

<Steps>
  <Step title="Configure the Sender Process">
    1. Open **FlowX.AI Designer** and create or edit the process that will send the message
    2. Add a **Message Throw Intermediate Event** node at the point where you want to trigger the other process
    3. Configure data that will be used for correlation (e.g., a key value like 'key1')

    <Frame>
      ![Correlation Data Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/correlation_data.png)
    </Frame>

    4. Configure the message correlation in the node properties:

    <Frame>
      ![Message Correlation Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_correlation.png)
    </Frame>
  </Step>

  <Step title="Configure the Receiver Process">
    1. Create or edit the process that should be started by the message
    2. Add a **Start Message Catch Event** node as the starting point
    3. Configure the node with:
       * The same message name used in the throw event (e.g., 'start\_correlation')
       * The correlation key in the Receive data tab (e.g., 'key1')
  </Step>

  <Step title="Test the Configuration">
    Run the sender process and watch as it automatically triggers the receiver process when the Message Throw Event is reached.

    <Frame>
      ![Message Start Event in Action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_with_message_event.gif)
    </Frame>
  </Step>
</Steps>

<Info>
  Message correlation is essential for message-based communication between processes. It's achieved through the message name (which must be identical in both throw and catch events) and the correlation key (or value).
</Info>

## Best practices

<Tip>
  **When implementing process initiation:**

  * **Choose the appropriate method** based on your use case (user-triggered, scheduled, event-based, etc.)
  * **Consider authentication requirements** for system-initiated processes
  * **Use correlation keys thoughtfully** to ensure reliable message delivery
  * **Test your initiation methods** thoroughly in a development environment
  * **Monitor process starts** to identify any failures or performance issues
  * **Document your initiation methods** for easier maintenance and troubleshooting
</Tip>

## Next steps

After setting up your process initiation methods, you can:

<CardGroup>
  <Card title="Configure Process Data Models" icon="database" href="../../building-blocks/process/process-data-model">
    Define the data structure for your process instances
  </Card>

  <Card title="Set Up User Interfaces" icon="palette" href="./creating-a-user-interface">
    Create user interfaces for human-interactive processes
  </Card>

  <Card title="Implement Business Rules" icon="code" href="../../building-blocks/actions/business-rule-action/business-rule-action">
    Add decision logic to your processes
  </Card>

  <Card title="Configure Integrations" icon="plug" href="../../platform-deep-dive/integrations/integration-designer">
    Connect your processes to external systems
  </Card>
</CardGroup>


# FlowX.AI Designer
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/overview

The FlowX.AI Designer is a collaborative, no-code, web-based application development environment, designed to facilitate the creation of web and mobile applications without the need for coding expertise.

<Frame>
  <video />
</Frame>

# Overview

The **FlowX.AI Designer** is a collaborative platform that empowers you to create sophisticated web and mobile applications without coding expertise. Let's explore the key capabilities available in the Designer:

<Tabs>
  <Tab title="Workspace Management">
    <Frame>
      ![Workspace Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
    </Frame>

    Workspaces provide isolated environments for organizing projects and controlling access:

    * Create dedicated spaces for different teams or departments
    * Manage user access and permissions at workspace level
    * Organize projects by business unit or use case
    * Maintain separation between development contexts
    * Control visibility and collaboration boundaries
  </Tab>

  <Tab title="Project Management">
    <Frame>
      ![Project Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)
    </Frame>

    Projects serve as a structured container that group all resources, dependencies, and configurations needed for specific use cases. They provide:

    * Centralized resource management
    * Version control capabilities
    * Build deployment across environments
    * Collaborative editing workflows
    * Modular organization of processes and assets
  </Tab>

  <Tab title="Process Design">
    <Frame>
      ![Process Design](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/prs_def.png)
    </Frame>

    The process designer allows you to:

    * Create and edit processes using BPMN 2.0 standards
    * Configure nodes with business rules and actions
    * Set up user tasks and system integrations
    * Establish decision logic and execution paths
    * Test and debug process flows
  </Tab>

  <Tab title="Content & UI">
    <Frame>
      ![UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_ui_designer.gif)
    </Frame>

    Create intuitive user interfaces and manage content with:

    * Drag-and-drop UI component assembly
    * Advanced navigator with layer management
    * Theme customization capabilities
    * Media library organization
    * Font and styling controls
  </Tab>

  <Tab title="Plugins & Integration">
    <Frame>
      ![Integrations](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/plugins_integrations.png)
    </Frame>

    Extend functionality with plugins and integrations:

    * Task management capabilities
    * Document generation and templates
    * Notification system configuration
    * Integration mapping and monitoring
    * API connection management
  </Tab>
</Tabs>

## Key features & capabilities

<CardGroup>
  <Card title="Workspace Management" icon="building">
    Organize projects into isolated workspaces with dedicated access control, enabling team separation and structured collaboration across departments.
  </Card>

  <Card title="Project & Library Management" icon="folder">
    Create and manage comprehensive workspaces with centralized resources, version control, and modular components that enable efficient collaboration.
  </Card>

  <Card title="Process Design & Monitoring" icon="arrow-progress">
    Design, debug, and monitor processes using BPMN 2.0 standards with tracking and performance analytics.
  </Card>

  <Card title="Content Management" icon="folder-grid">
    Manage enumerations, substitution tags, languages, media, fonts, and themes with comprehensive organization tools.
  </Card>

  <Card title="UI Design" icon="pen-ruler">
    Create intuitive interfaces with an advanced navigator, component library, and flexible styling options.
  </Card>

  <Card title="Plugin Ecosystem" icon="puzzle-piece-simple">
    Extend functionality with task management, notification, and document generation plugins for comprehensive solutions.
  </Card>

  <Card title="Integration Tools" icon="link">
    Configure and monitor integrations between the FlowX Engine, plugins, and external systems with visual mapping tools.
  </Card>

  <Card title="Platform Monitoring" icon="signal-bars">
    Track system health, component versions, and performance metrics with comprehensive monitoring tools.
  </Card>

  <Card title="AI Assistance" icon="robot">
    Accelerate development with AI-powered suggestions, optimization recommendations, and contextual help.
  </Card>
</CardGroup>

<Note>
  Depending on your access rights, some features and tabs might not be visible. For more information, check [Access Management](../../setup-guides/access-management/access-management-overview) section.
</Note>

## Detailed component overview

<AccordionGroup>
  <Accordion title="Workspaces" icon="building">
    <Frame>
      ![Workspace Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
    </Frame>

    Workspaces are the top-level organizational unit in FlowX.AI Designer, providing isolated environments where teams can collaborate on projects with controlled access and visibility.

    ### Key Capabilities

    <Steps>
      <Step title="Workspace Creation & Management">
        Create dedicated workspaces for different teams, departments, or business units. Each workspace acts as an independent container with its own projects and resources.
      </Step>

      <Step title="Access Control">
        Configure workspace-level permissions to control who can view, edit, or manage projects within each workspace. Administrators can assign users and groups specific roles.
      </Step>

      <Step title="Project Organization">
        Group related projects together within a workspace for better organization and discoverability. Projects inherit workspace-level settings and permissions.
      </Step>

      <Step title="Team Collaboration">
        Enable focused collaboration by bringing together stakeholders who need to work on related projects, while maintaining separation from other teams.
      </Step>
    </Steps>

    ### Benefits

    * **Isolation**: Keep different teams' work separate and secure
    * **Flexibility**: Organize workspaces by department, product line, or any business structure
    * **Security**: Control access at the workspace level for enhanced governance
    * **Clarity**: Reduce clutter by showing users only relevant workspaces and projects

    <Card title="Workspace Access Rights" href="../../setup-guides/access-management/workspaces-access-rights" icon="lock">
      Learn more about configuring workspace access rights
    </Card>
  </Accordion>

  <Accordion title="Projects & Libraries" icon="folder">
    <Tabs>
      <Tab title="Projects">
        A project groups resources that represent a project's entire lifecycle. It's not just a collection of processes; it's an organized workspace containing all dependencies required for that project. It enables:

        * Centralized resource management
        * Version control with history tracking
        * Build deployment across environments
        * Collaborative workflows with simultaneous editing
        * Modular organization of processes and assets

        <Frame>
          ![Project Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)
        </Frame>

        <Card title="Learn More About Projects" href="../projects/managing-applications/application" icon="folder" />
      </Tab>

      <Tab title="Libraries">
        A library is a specialized project type designed to store and share reusable resources across multiple projects:

        * Share processes, enumerations, and media assets
        * Enable centralized resource management
        * Provide version-controlled dependency management
        * Support modular development approaches
        * Include comprehensive dependency tracking
        * Offer comprehensive import/export functionality
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Process Management" icon="arrow-progress">
    <Tabs>
      <Tab title="Process Definitions">
        A **process definition** is uniquely identified by its name and version number. The process designer provides:

        * [Process definition](../building-blocks/process/process-definition) management
        * Versioning history with comparison capabilities
        * Debugging tools for process execution
        * Version comparison for change identification
        * BPMN 2.0 standard compliance

        <Frame>
          ![Process Definitions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_process_definitions.gif)
        </Frame>

        <CardGroup>
          <Card title="Process Definition" href="../building-blocks/process/process-definition" icon="diagram-project" />

          <Card title="Managing a Process Flow" href="../flowx-designer/managing-a-project-flow/" icon="arrow-right-arrow-left" />
        </CardGroup>
      </Tab>

      <Tab title="Active Processes">
        The complete list of active **process instances** is visible from the FlowX.AI Designer. Monitor and manage running process instances with:

        * Filtering by process definition names
        * Search by unique process ID
        * View current process status and data
        * [Token](../building-blocks/token) instance and content inspection
        * [Subprocess](../building-blocks/process/subprocess) management
        * Real-time monitoring with performance metrics
        * Advanced filtering for process management

        <Frame>
          ![Active Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_active_process.png)
        </Frame>

        <Card title="Process Instance Management" href="../projects/runtime/active-process/process-instance" icon="play" />
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Content Management" icon="folder-grid">
    <Grid>
      <div>
        <h4>Data & Localization</h4>

        <Steps>
          <Step title="Enumerations">
            Manage static value definitions that can be used in UI components or templates with bulk import/export capabilities.
          </Step>

          <Step title="Substitution Tags">
            Generate dynamic content across the platform with context-aware tag suggestions for localization.
          </Step>

          <Step title="Languages">
            Configure language-specific enumeration values with comprehensive character set support.
          </Step>

          <Step title="Source Systems">
            Connect to multiple data sources for [enumeration values](../platform-deep-dive/core-extensions/content-management/enumerations) with third-party system integration.
          </Step>
        </Steps>
      </div>

      <div>
        <h4>Media & Styling</h4>

        <Steps>
          <Step title="Media Library">
            Centrally manage various media files with metadata tagging and optimization capabilities.
          </Step>

          <Step title="Font Management">
            Upload and manage font files including variable fonts with subset creation for performance.
          </Step>

          <Step title="Themes">
            Personalize application appearance with atomic design principles and multi-device previewing.
          </Step>
        </Steps>
      </div>
    </Grid>

    <Frame>
      ![Content Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_cms.gif)
    </Frame>

    <Info>
      You need to deploy the CMS service in your infrastructure before you can start defining and using custom content types.
    </Info>

    <CardGroup>
      <Card title="Headless CMS" href="../platform-deep-dive/core-extensions/content-management/content-management" icon="server" />

      <Card title="CMS Setup Guide" href="../../setup-guides/cms-setup" icon="gears" />
    </CardGroup>
  </Accordion>

  <Accordion title="Plugins" icon="puzzle-piece-simple">
    <CardGroup>
      <Card title="Task Management" icon="list-check" href="../platform-deep-dive/core-extensions/task-management/task-management-overview">
        <Frame>
          ![Task Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_task_manager.png)
        </Frame>

        Track and assign activities with prioritization, history tracking, and performance analytics. The Task Manager provides a business-oriented view of processes with assignment-level interactions.
      </Card>

      <Card title="Notification Templates" icon="bell" href="../platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview">
        <Frame>
          ![Notification Templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_notification_templates.png)
        </Frame>

        Create, edit, and activate/deactivate notification templates for multiple channels (SMS, email, push notifications) with scheduling, monitoring, and personalization capabilities.
      </Card>

      <Card title="Document Templates" icon="file-lines" href="../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview">
        <Frame>
          ![Document Templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_documents.png)
        </Frame>

        Generate documents based on custom templates with process data, convert between formats, split documents, add barcodes/signatures, and manage version control with conditional template variables.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="System Settings" icon="gears">
    <Tabs>
      <Tab title="Configuration Parameters">
        <Frame>
          ![Generic Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_generic_params.png)
        </Frame>

        Manage environment-specific settings with:

        * Key-value parameter definition
        * Environment-specific value configuration
        * Parameter grouping and categorization
        * Environment comparison tools
        * Import/export capabilities

        <Warning>
          The maximum length of a parameter input value is 255 characters.
        </Warning>
      </Tab>

      <Tab title="Access Management">
        <Frame>
          ![Access Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_access_mng.png)
        </Frame>

        Administrate users, roles and groups through:

        * Integration with Keycloak/[RH-SSO](https://access.redhat.com/products/red-hat-single-sign-on)
        * Role-based access control
        * Granular permission management
        * User onboarding templates
        * Group organization

        <Card title="Access Management" href="../../setup-guides/access-management/access-management-overview" icon="lock" />
      </Tab>

      <Tab title="Integration Management">
        <Frame>
          ![Integration Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_integrations.png)
        </Frame>

        Configure and monitor connections between:

        * [FlowX Process engine](../platform-deep-dive/core-components/flowx-engine)
        * [Platform plugins](../platform-deep-dive/plugins/custom-plugins/)
        * External adapters and systems
        * Scenario-specific configurations (OTP, documents, notifications)
        * Visual mapping tools
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Platform Status" icon="signal-bars">
    <Frame>
      ![Platform Status](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/platform_status.png)
    </Frame>

    The Platform Status panel is also where you check **which version of FlowX your environment is running**. It shows the platform version alongside each service's required vs. running version, so you can confirm the deployed version at a glance.

    Other capabilities:

    * Health status monitoring for all FlowX services and custom connectors
    * Component version checking (running vs. required)
    * Performance metrics and resource utilization statistics
    * System alerts
    * Historical data for trend analysis
  </Accordion>

  <Accordion title="UI Designer" icon="pen-ruler">
    <Frame>
      ![UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/ui_designer.png)
    </Frame>

    The UI Designer provides a comprehensive environment for creating intuitive user interfaces with:

    * Enhanced UI layer panel for intuitive design element management
    * Improved drag and drop functionality for precise component placement
    * Flexible root component management for form groups and containers
    * Clear component hierarchy visualization with navigation controls
    * Rich component library with customization options
    * Integration with themes and styling capabilities

    <Card title="UI Designer Documentation" href="../building-blocks/ui-designer/ui-designer" icon="book">
      Learn more about UI Designer capabilities and components
    </Card>
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="Managing a Process Flow" href="../flowx-designer/managing-a-project-flow/" icon="file">
  Learn how to create and manage a process from scratch
</Card>


# Tutorial: Build a credit card application
Source: https://docs.flowx.ai/5.9/docs/getting-started/building-your-first-proc

Learn FlowX.AI by building a complete credit card request flow with forms, integrations, and notifications.

In this tutorial, you'll build a credit card application process from scratch. By the end, you'll understand how to:

* Design a BPMN process with multiple node types
* Create user-facing forms
* Integrate with external systems
* Handle branching logic based on business rules
* Send notifications

<Info>
  **Time required:** 30-45 minutes

  **Prerequisites:**

  * Access to FlowX Designer
  * A workspace and project set up ([create one here](/5.9/docs/projects/workspaces))
</Info>

***

## What you'll build

A customer requests a new credit card through a bank app. The process:

1. Collects personal information
2. Checks credit score automatically
3. Assigns a card type based on the score
4. Sends confirmation email
5. Lets the user pick a branch for card pickup

Here's the complete BPMN diagram:

<Frame>
  ![Credit card application process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/request_a_credit_card_new.png)
</Frame>

<Card title="Download this process" href="https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sample_bpmn_process_new_credit_card.bpmn" icon="download">
  Import this BPMN file to follow along or explore the finished result.
</Card>

***

## Step 1: Create the process

<Steps>
  <Step title="Open your project">
    Navigate to **FlowX Designer** → your workspace → your project.
  </Step>

  <Step title="Create a new process">
    Click **New** → **Process**. Name it `credit-card-request`.
  </Step>

  <Step title="Add a Start Event">
    Drag a **Start Event** node onto the canvas. This is where the process begins when a customer opens the credit card application.
  </Step>
</Steps>

<Card title="Learn more about processes" href="/5.9/docs/building-blocks/process/process" icon="book" />

***

## Step 2: Collect user data (User Task)

The first step is collecting the customer's personal information.

<Steps>
  <Step title="Add a User Task">
    Drag a **User Task** node after the Start Event. Name it `Fill Personal Data`.
  </Step>

  <Step title="Design the form">
    In the node settings, open the **UI Designer**. Add form fields:

    * Full name (text input)
    * Email (text input with email validation)
    * Date of birth (date picker)
    * Annual income (number input)
  </Step>

  <Step title="Configure the data model">
    Map each field to a key in your data model:

    * `application.fullName`
    * `application.email`
    * `application.dateOfBirth`
    * `application.annualIncome`
  </Step>
</Steps>

<Card title="Learn more about User Tasks" href="/5.9/docs/building-blocks/node/user-task-node" icon="book" />

***

## Step 3: Check credit score (Service Task)

Now we'll call an external credit scoring service automatically.

<Steps>
  <Step title="Add a Send Message Task">
    This sends the customer data to your credit score adapter.

    Configure the Kafka topic to send to your credit scoring integration.
  </Step>

  <Step title="Add a Receive Message Task">
    This waits for the credit score response.

    Map the response to `application.creditScore`.
  </Step>
</Steps>

<Tip>
  Don't have a credit score service? For testing, use a **Business Rule** node to simulate a score based on annual income.
</Tip>

<Card title="Learn more about integrations" href="/5.9/docs/platform-deep-dive/integrations/integrations-overview" icon="book" />

***

## Step 4: Branch based on credit score (Exclusive Gateway)

Different credit scores qualify for different card types.

<Steps>
  <Step title="Add an Exclusive Gateway">
    This creates a decision point based on the credit score.
  </Step>

  <Step title="Configure branch conditions">
    * **Branch 1:** `application.creditScore >= 700` → Premium card
    * **Branch 2:** `application.creditScore >= 500` → Standard card
    * **Branch 3:** Default → Basic card
  </Step>

  <Step title="Add Service Tasks for each branch">
    Each branch sets the card type:

    ```javascript theme={"system"}
    output.put("application.cardType", "PREMIUM");
    ```
  </Step>

  <Step title="Add a Closing Gateway">
    Merge the branches back together after the card type is set.
  </Step>
</Steps>

<Card title="Learn more about Gateways" href="/5.9/docs/building-blocks/node/exclusive-gateway-node" icon="book" />

***

## Step 5: Show results and confirm (User Task)

Let the customer review their card type and confirm.

<Steps>
  <Step title="Add a User Task">
    Name it `Review and Confirm`.
  </Step>

  <Step title="Design the confirmation screen">
    Display the assigned card type and benefits. Add a **Confirm** button.
  </Step>
</Steps>

***

## Step 6: Send notification and register (Parallel Gateway)

After confirmation, two things happen simultaneously:

<Steps>
  <Step title="Add a Parallel Gateway">
    This splits the flow into parallel branches.
  </Step>

  <Step title="Branch 1: Send confirmation email">
    Add a **Send Message Task** that triggers the notification plugin.

    Configure email template with customer name and card type.
  </Step>

  <Step title="Branch 2: Register in bank system">
    Add a **Send Message Task** to your bank system adapter.

    This creates the card request in your core banking system.
  </Step>

  <Step title="Add a Closing Parallel Gateway">
    Wait for both branches to complete before continuing.
  </Step>
</Steps>

<Card title="Learn more about Notifications" href="/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview" icon="book" />

***

## Step 7: Select pickup location (User Task)

Let the customer choose where to pick up their card.

<Steps>
  <Step title="Add a Service Task to fetch locations">
    Call an API (like Google Maps) to get nearby branches based on customer address.
  </Step>

  <Step title="Add a User Task">
    Display the top 3 branches as selectable options.
  </Step>
</Steps>

***

## Step 8: End the process

<Steps>
  <Step title="Add a Receive Message Task">
    This waits for confirmation that the customer picked up the card (from branch system).
  </Step>

  <Step title="Add an End Event">
    The process completes.
  </Step>
</Steps>

***

## Test your process

<Steps>
  <Step title="Save and validate">
    Click **Save**. Fix any validation errors shown.
  </Step>

  <Step title="Start a process instance">
    Click **Run** to start a new instance. Fill in the forms and watch the process flow.
  </Step>

  <Step title="Check the token">
    Use the **Process Instance** view to see where the token is and inspect data at each step.
  </Step>
</Steps>

***

## What you learned

You've built a complete process that demonstrates:

| Concept               | How you used it                                |
| --------------------- | ---------------------------------------------- |
| **User Tasks**        | Collecting data, showing confirmations         |
| **Service Tasks**     | Calling external APIs, setting data            |
| **Exclusive Gateway** | Branching based on credit score                |
| **Parallel Gateway**  | Running email + registration simultaneously    |
| **Integrations**      | Credit score check, bank system, notifications |

***

## Next steps

<CardGroup>
  <Card title="UI components" href="/5.9/docs/building-blocks/ui-designer/ui-designer" icon="browser">
    Learn all available form and display components
  </Card>

  <Card title="Business rules" href="/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action" icon="gavel">
    Add complex logic with DMN or scripts
  </Card>

  <Card title="Error handling" href="/5.9/docs/building-blocks/node/error-events" icon="triangle-exclamation">
    Handle failures gracefully
  </Card>

  <Card title="FlowX Academy" href="https://academy.flowx.ai" icon="graduation-cap">
    Take structured courses with certifications
  </Card>
</CardGroup>


# FlowX.AI documentation
Source: https://docs.flowx.ai/5.9/docs/introduction

Build enterprise applications and deploy AI agents for banking, insurance, and logistics

<iframe />

FlowX.AI is an enterprise platform for building business apps in regulated industries. Connect your existing systems, design processes visually, and launch modern solutions without replacing your core infrastructure.

***

## Choose your path

<CardGroup>
  <Card title="I want to build apps" icon="rocket" href="/5.9/docs/getting-started/building-your-first-proc">
    **Start here.** Create your first process with UI in the visual designer.
  </Card>

  <Card title="I need to deploy FlowX" icon="server" href="/5.9/setup-guides/setup-guides-overview">
    **Platform admins.** Install and configure FlowX in your infrastructure.
  </Card>

  <Card title="I want to integrate APIs" icon="code" href="/5.9/sdks/sdks-overview">
    **Developers.** Use our SDKs (Angular, React, iOS, Android) or REST APIs.
  </Card>

  <Card title="I want to deploy AI agents" icon="robot" href="/5.9/ai-platform/ai-in-flowx">
    **AI builders.** Build and deploy AI agents for your business processes.
  </Card>
</CardGroup>

***

## What you can build

Real examples of what teams build with FlowX.AI:

<AccordionGroup>
  <Accordion title="Customer onboarding" icon="user-plus">
    **The problem:** Onboarding takes weeks, requires multiple systems, and drops customers due to friction.

    **What you build:** A unified digital journey: ID verification, document upload, KYC checks, and account creation, all in one flow that connects to your core banking system.

    **Result:** Onboarding in minutes instead of days. Full audit trail for compliance.
  </Accordion>

  <Accordion title="Loan origination" icon="money-bill">
    **The problem:** Loan applications require manual data entry across systems, slow credit decisions, and paper-based approvals.

    **What you build:** End-to-end digital lending: application capture, credit scoring integration, automated decisioning, e-signature, and disbursement, with human review where needed.

    **Result:** Faster time-to-yes, reduced operational costs, consistent decisions.
  </Accordion>

  <Accordion title="Claims processing" icon="file-invoice">
    **The problem:** Claims intake is manual, assessment is slow, and customers wait weeks for resolution.

    **What you build:** First notice of loss capture, document collection, AI-assisted damage assessment, automated routing to adjusters, and settlement workflows.

    **Result:** Claims resolved in days, not weeks. Better customer experience.
  </Accordion>

  <Accordion title="Back-office automation" icon="gears">
    **The problem:** Internal processes rely on emails, spreadsheets, and tribal knowledge.

    **What you build:** Structured workflows for approvals, task assignment, escalations, and reporting, with visibility into bottlenecks.

    **Result:** Consistent processes, clear accountability, reduced errors.
  </Accordion>
</AccordionGroup>

***

## How it works

<Steps>
  <Step title="Design your process">
    Use the visual designer to map your business workflow using BPMN 2.0. Drag and drop nodes, define business rules, and set up integrations. No coding required for standard flows.

    <Card title="FlowX Designer overview" icon="pencil-ruler" href="/5.9/docs/flowx-designer/overview" />
  </Step>

  <Step title="Build your UI">
    Create user interfaces by configuring components: forms, tables, file uploads, and signatures. The UI automatically adapts to web and mobile.

    <Card title="UI components" icon="browser" href="/5.9/docs/building-blocks/ui-designer/ui-designer" />
  </Step>

  <Step title="Connect your systems">
    Integrate with your existing infrastructure using REST APIs, Kafka, or custom connectors. FlowX orchestrates the data flow between systems.

    <Card title="Integrations" icon="plug" href="/5.9/docs/platform-deep-dive/integrations/integrations-overview" />
  </Step>

  <Step title="Deploy and run">
    Deploy to FlowX SaaS or your own infrastructure. Monitor processes, handle exceptions, and iterate based on real usage.

    <Card title="Deployment options" icon="cloud" href="/5.9/docs/saas/saas-overview" />
  </Step>
</Steps>

***

## Key concepts

New to FlowX? Here's what you need to know:

| Concept         | What it is                                                                         |
| --------------- | ---------------------------------------------------------------------------------- |
| **Process**     | A business workflow defined in BPMN 2.0. Contains nodes, actions, and UI.          |
| **Node**        | A step in your process: user tasks, service tasks, gateways, events.               |
| **Action**      | What happens at a node: save data, call API, send notification, run business rule. |
| **Token**       | Tracks where a process instance is. Multiple tokens = parallel execution.          |
| **Data model**  | The structure of data in your process. Defined as keys with types.                 |
| **Integration** | Connection to external systems via REST, Kafka, or custom protocols.               |

<Card title="Full glossary" icon="book" href="/5.9/docs/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn" />

***

## Get help

<CardGroup>
  <Card title="FlowX Academy" icon="graduation-cap" href="https://academy.flowx.ai">
    Free courses and certifications
  </Card>

  <Card title="Support" icon="headset" href="https://flowxai.zendesk.com/">
    Contact the support team
  </Card>

  <Card title="Release notes" icon="newspaper" href="/release-notes/overview">
    Latest updates and changes
  </Card>
</CardGroup>


# Data architecture
Source: https://docs.flowx.ai/5.9/docs/platform-overview/data-architecture

Which data stores FlowX.AI uses, what each stores, and how they fit together.

## Overview

FlowX.AI uses multiple specialized data stores, each chosen for specific workload characteristics. They fall into two categories:

* **Embedded data components** — shipped with the platform, managed by FlowX.AI
* **Platform data services** — third-party dependencies deployed by your team

```mermaid theme={"system"}
flowchart LR
    FX["FlowX.AI Platform"]

    FX -->|"process definitions, instance state,\nplatform config, metadata"| PG[("PostgreSQL")]
    FX -->|"runtime config, workflow state,\nFlowX Database"| MONGO[("MongoDB")]
    FX -->|"cache, sessions,\ndistributed locks"| REDIS[("Redis")]
    FX -->|"event streaming,\nasync messaging"| KAFKA[("Kafka")]
    FX -->|"files, documents,\nbinary assets"| S3[("S3-compatible\nobject storage")]
    FX -->|"audit logs,\nsearch indexes"| ES[("Elasticsearch")]
    FX -->|"vector embeddings,\nsemantic retrieval"| QD[("Qdrant")]

    style PG fill:#336791,color:#fff
    style MONGO fill:#4DB33D,color:#fff
    style REDIS fill:#DC382D,color:#fff
    style KAFKA fill:#231F20,color:#fff
    style S3 fill:#FF9900,color:#fff
    style ES fill:#FED10A,color:#000
    style QD fill:#DC244C,color:#fff
```

***

## Embedded data components

<Note>
  Embedded data components are delivered as part of the FlowX.AI platform (Docker images + Helm charts). They run on Kubernetes only, and their versioning is managed by FlowX.AI. These components are included in the standard deployment and cannot be replaced by alternative implementations.
</Note>

<Card title="Qdrant" icon="diagram-project" href="https://qdrant.tech/documentation/">
  **Type:** Vector database

  Qdrant is used by the AI Platform RAG path (`knowledgebase-rag`, `embedder`, `knowledgebase-indexer-v2`) and by AI agents for semantic retrieval. It stores vector embeddings and serves similarity search over indexed knowledge.
</Card>

***

## Platform data services

<Info>
  The following data services are required by the FlowX.AI platform but are third-party dependencies. You choose the deployment model — managed service or self-hosted, inside or outside the Kubernetes cluster — according to your enterprise standards. FlowX.AI connects to these services via configuration.

  For supported versions and compatibility details, see the [Third-party components](../platform-deep-dive/third-party-components#compatibility-matrix) compatibility matrix.
</Info>

### Relational storage — PostgreSQL / Oracle

PostgreSQL is the primary relational database and system-of-record for most core services. Oracle Database is also supported as an alternative. They store:

* Process definitions and metadata
* Runtime instance state
* Platform configuration
* Administrative data

Most FlowX.AI microservices use PostgreSQL or Oracle as their authoritative storage layer.

### Document storage — MongoDB

MongoDB provides document-oriented storage for unstructured and semi-structured content. It stores:

* Runtime configuration
* Runtime workflow state
* Flexible data structures used by apps and integrations

MongoDB is also the storage layer for [FlowX Database](../platform-deep-dive/integrations/flowx-database) — a cross-instance, long-term storage feature that enables apps to persist and query data beyond a single process instance.

### Caching — Redis

Redis is an in-memory cache used for performance optimization across the platform. It stores:

* Cached process definitions
* Compiled scripts
* Transient session data
* Distributed locks across microservices

<Info>
  Redis is used strictly for short-lived, performance-related data and is **not** a system-of-record. Long-term persistence is handled by PostgreSQL and MongoDB.
</Info>

### Event streaming — Kafka

Kafka is the event streaming backbone that enables asynchronous, event-driven communication between microservices. It handles:

* Internal event propagation between platform services
* External integration messaging
* Decoupled processing workflows

<Info>
  Kafka is used for transient message propagation. Authoritative business data is persisted in PostgreSQL and MongoDB, not in Kafka.
</Info>

### Object storage — S3-compatible

S3-compatible object storage provides persistent file storage. It stores:

* File attachments
* Document outputs (generated PDFs, converted files)
* Large binary assets

FlowX.AI accesses object storage via an S3-compatible interface.

<Tip>
  For providers without native S3 support (such as Azure Blob Storage), an S3 proxy is required to expose an S3-compatible interface. If you use a native S3 service (like AWS S3), no proxy is needed.
</Tip>

### Search and indexing — Elasticsearch

Elasticsearch is used primarily for audit logging and full-text search across workflow and runtime data. It stores:

* Searchable representations of audit events
* Platform activity logs
* Indexed workflow data for fast retrieval

Elasticsearch is optimized for fast search and traceability rather than primary data storage.

***

## Quick reference

| Data Store              | Role                 | What it stores                                        | Persistence |
| ----------------------- | -------------------- | ----------------------------------------------------- | ----------- |
| **PostgreSQL / Oracle** | System of record     | Process definitions, config, metadata, instance state | Permanent   |
| **MongoDB**             | Document store       | Runtime state, flexible data, FlowX Database          | Permanent   |
| **Redis**               | Cache                | Process definitions cache, sessions, locks            | Transient   |
| **Kafka**               | Event streaming      | Inter-service messages, integration events            | Transient   |
| **Object Storage**      | File store           | Attachments, documents, binary assets                 | Permanent   |
| **Elasticsearch**       | Search engine        | Audit logs, indexed workflow data                     | Permanent   |
| **Qdrant**              | Vector database (AI) | Embeddings for RAG and semantic retrieval             | Permanent   |

***

## Service-level database mapping

The tables and diagrams below show which FlowX.AI services connect to which databases and what operations they perform. This is useful for infrastructure sizing, backup planning, and troubleshooting.

### PostgreSQL databases

Each core service owns its own PostgreSQL database and manages its schema through Liquibase migrations at startup.

```mermaid theme={"system"}
flowchart LR
    subgraph Services
        ADM["Admin"]
        ADV["Advancing Controller"]
        APPM["Application Manager"]
        AUTH["Authorization System"]
        DOC["Document Plugin"]
        EMAIL["Email Gateway"]
        LIC["License"]
        ORG["Organization Manager"]
        ENG["Process Engine"]
        TASK["Task Management"]
        DSYNC["Data Sync"]
    end

    subgraph PostgreSQL
        ADMDB[("flowxadmin")]
        ADVDB[("advancing")]
        APPMDB[("app_manager")]
        AUTHDB[("auth_system")]
        DOCDB[("document")]
        EMAILDB[("email_gateway")]
        LICDB[("license")]
        ORGDB[("org_manager")]
        ENGDB[("process_engine")]
    end

    ADM -->|"creates, reads, writes"| ADMDB
    ADV -->|"creates, reads, writes"| ADVDB
    APPM -->|"creates, reads, writes"| APPMDB
    AUTH -->|"creates, reads, writes"| AUTHDB
    DOC -->|"creates, reads, writes"| DOCDB
    EMAIL -->|"creates, reads, writes"| EMAILDB
    LIC -->|"creates, reads, writes"| LICDB
    ORG -->|"creates, reads, writes"| ORGDB
    ENG -->|"creates, reads, writes"| ENGDB
    TASK -->|"reads, writes"| ENGDB
    DSYNC -.->|"manages migrations"| APPMDB
    DSYNC -.->|"manages migrations"| AUTHDB
    DSYNC -.->|"manages migrations"| ENGDB
```

| Service              | Database         | Operations             |
| -------------------- | ---------------- | ---------------------- |
| Admin                | `flowxadmin`     | Creates, reads, writes |
| Advancing Controller | `advancing`      | Creates, reads, writes |
| Application Manager  | `app_manager`    | Creates, reads, writes |
| Authorization System | `auth_system`    | Creates, reads, writes |
| Document Plugin      | `document`       | Creates, reads, writes |
| Email Gateway        | `email_gateway`  | Creates, reads, writes |
| License              | `license`        | Creates, reads, writes |
| Organization Manager | `org_manager`    | Creates, reads, writes |
| Process Engine       | `process_engine` | Creates, reads, writes |
| Task Management      | `process_engine` | Reads, writes          |

<Info>
  Task Management shares the `process_engine` database with Process Engine. Data Sync acts as a centralized migration coordinator for `app_manager`, `auth_system`, and `process_engine`.
</Info>

### MongoDB databases

Each service manages its own MongoDB database. The `app-runtime` database is a shared read-only dependency for multiple services.

```mermaid theme={"system"}
flowchart LR
    subgraph Services
        ADM["Admin"]
        APPM["Application Manager"]
        CMS["CMS Core"]
        DOC["Document Plugin"]
        INTD["Integration Designer"]
        NOTIF["Notification Plugin"]
        SCHED["Scheduler"]
        TASK["Task Management"]
        ENG["Process Engine"]
        EMAIL["Email Gateway"]
        NOSQL["NoSQL DB Runner"]
    end

    subgraph MongoDB
        DM[("data-model")]
        AR[("app-runtime")]
        CMSDB[("cms-core")]
        DOCDB[("document")]
        NOTIFDB[("notification")]
        TASKDB[("task-management-plugin")]
        INTDDB[("integration-designer")]
        NOSQLDB[("nosql-db-runner")]
    end

    ADM -->|"creates, reads, writes"| DM
    APPM -->|"creates, reads, writes"| AR
    CMS -->|"creates, reads, writes"| CMSDB
    DOC -->|"creates, reads, writes"| DOCDB
    DOC -->|"reads"| AR
    INTD -->|"creates, reads, writes"| INTDDB
    INTD -->|"reads"| AR
    NOTIF -->|"creates, reads, writes"| NOTIFDB
    NOTIF -->|"reads"| AR
    SCHED -->|"creates, reads, writes"| NOTIFDB
    TASK -->|"creates, reads, writes"| TASKDB
    TASK -->|"reads"| AR
    ENG -->|"reads"| AR
    EMAIL -->|"reads"| AR
    NOSQL -->|"creates, reads, writes"| NOSQLDB
```

| Service              | Database                 | Operations             |
| -------------------- | ------------------------ | ---------------------- |
| Admin                | `data-model`             | Creates, reads, writes |
| Application Manager  | `app-runtime`            | Creates, reads, writes |
| CMS Core             | `cms-core`               | Creates, reads, writes |
| Document Plugin      | `document`               | Creates, reads, writes |
| Document Plugin      | `app-runtime`            | Reads                  |
| Integration Designer | `integration-designer`   | Creates, reads, writes |
| Integration Designer | `app-runtime`            | Reads                  |
| Notification Plugin  | `notification`           | Creates, reads, writes |
| Notification Plugin  | `app-runtime`            | Reads                  |
| Scheduler            | `notification`           | Creates, reads, writes |
| Task Management      | `task-management-plugin` | Creates, reads, writes |
| Task Management      | `app-runtime`            | Reads                  |
| Process Engine       | `app-runtime`            | Reads                  |
| Email Gateway        | `app-runtime`            | Reads                  |
| NoSQL DB Runner      | `nosql-db-runner`        | Creates, reads, writes |

<Warning>
  The `app-runtime` database is created by Application Manager and read by 6 other services. It contains runtime configuration, build data, and deployed app state. Availability of this database is critical for runtime operations.
</Warning>

### Elasticsearch indexes

| Service        | Index                  | Operations             |
| -------------- | ---------------------- | ---------------------- |
| Audit Core     | Audit index            | Creates, reads, writes |
| Process Engine | Process instance index | Creates, reads, writes |
| Data Search    | Process instance index | Reads                  |

### Redis

All core services use Redis for **caching only** via Spring Cache Manager. Events Gateway additionally uses Redis for pub/sub messaging.

Services using Redis for caching: Admin, Application Manager, Authorization System, CMS Core, Document Plugin, Email Gateway, Integration Designer, License, Notification Plugin, Organization Manager, Process Engine, Task Management.

| Service        | Usage          |
| -------------- | -------------- |
| Events Gateway | Cache, pub/sub |

### S3-compatible object storage buckets

<Info>
  Bucket names shown are defaults from the configuration and are configurable via environment variables (e.g., `MINIO_BUCKET_PREFIX`). Your deployment may use different names. In some deployments, multiple services may share the same bucket. Ensure cross-bucket read access is configured where needed.
</Info>

| Service              | Default Bucket               | Env Variable          | Purpose                                    |
| -------------------- | ---------------------------- | --------------------- | ------------------------------------------ |
| Application Manager  | `applications-bucket`        | —                     | App builds and exported/imported resources |
| CMS Core             | `media-library-bucket`       | —                     | Public media assets                        |
| CMS Core             | `cms-private-storage-bucket` | —                     | Private theme and font files               |
| Document Plugin      | `flowx-dev-bucket`           | `MINIO_BUCKET_PREFIX` | Document templates and generated files     |
| Document Plugin      | `temp-bucket`                | `MINIO_TEMP_BUCKET`   | Temporary processing files                 |
| Integration Designer | `workflows-bucket`           | —                     | Workflow definitions and test files        |
| Notification Plugin  | `flowx-dev`                  | `MINIO_BUCKET_PREFIX` | Notification templates and attachments     |

***

## Related resources

<CardGroup>
  <Card title="Third-party components" href="../platform-deep-dive/third-party-components" icon="cube">
    Supported versions and compatibility matrix
  </Card>

  <Card title="FlowX Database" href="../platform-deep-dive/integrations/flowx-database" icon="database">
    Cross-instance, long-term data storage using MongoDB
  </Card>

  <Card title="FlowX.AI architecture" href="./flowx-architecture" icon="diagram-project">
    Overall platform architecture and microservices overview
  </Card>

  <Card title="Redis configuration" href="../../setup-guides/redis-configuration" icon="fire">
    Redis deployment modes and configuration
  </Card>
</CardGroup>


# FlowX.AI architecture
Source: https://docs.flowx.ai/5.9/docs/platform-overview/flowx-architecture

FlowX.AI is built on a layered microservices architecture with event-driven communication. This page covers the 23+ backend services, AI Platform, client SDKs, and infrastructure that make up the platform.

## Overview

FlowX.AI is an event-driven platform built on specialized microservices that communicate primarily through Apache Kafka. The architecture is organized into distinct layers, each responsible for a specific concern — from process execution and application lifecycle management to authorization, content delivery, and AI-powered automation.

All backend services are containerized and deployed on Kubernetes. Client applications connect through an API Gateway that handles OAuth2 token validation and request routing.

<Info>
  For detailed database-to-service mapping, storage types, and sizing guidance, see the [Data architecture](./data-architecture) page.
</Info>

***

## Architecture overview

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/flowx-architecture-5.9.svg)
</Frame>

The diagram above shows the main architectural layers and how they interact. Almost all inter-service communication flows through Kafka, while the Events Gateway pushes real-time updates to clients via Server-Sent Events (SSE).

<Tip>
  All Kafka topics follow a consistent naming convention: `ai.flowx.{service}.{action}.v1` (for example, `ai.flowx.core.trigger.advance.process.v1`).
</Tip>

***

## FlowX Designer

The **FlowX Designer** is a collaborative, no-code/full-code web application for building and managing processes, UIs, integrations, and other application components.

* **BPMN editor** — visual process designer built on Fabric.js canvas
* **UI designer** — drag-and-drop interface builder for web and mobile
* **Data model builder** — schema design and management
* **Integration designer UI** — visual workflow builder for external system connections
* **Script builder** — Monaco-based code editor for business rules (JavaScript, Python, MVEL, Groovy)
* **AI features** — embedded config-time agents, conversation system, command center
* **CMS, theme editor, access management** — content, branding, and permissions configuration

The Designer communicates with backend services through REST APIs, GraphQL, SSE, and WebSocket connections, all routed through the API Gateway.

<Tip>
  The Designer runs in the browser and is not deployed as part of the backend infrastructure. It connects to backend services through the API Gateway.
</Tip>

<Card title="FlowX Designer" href="../flowx-designer/overview" icon="pencil" />

***

## Core Engine layer

The Core Engine layer handles workflow execution, process orchestration, and real-time event delivery.

### Process Engine

The **Process Engine** is the central orchestration service that executes BPMN 2.0 process definitions and manages process instance lifecycles.

* Executes business processes and coordinates real-time interactions between users, systems, and data
* Manages process instances from creation through completion
* Supports multiple scripting languages: JavaScript (GraalJS), Python 3 (GraalPy), MVEL, and Groovy
* Dynamically generates and delivers UI components based on process state

**Data stores:** PostgreSQL or Oracle (`process_engine`), MongoDB (`app-runtime` read), Redis (cache), Elasticsearch (indexing)

<Card title="Process Engine" href="../platform-deep-dive/core-components/flowx-engine" icon="gears" />

### Advancing Controller

The **Advancing Controller** ensures efficient process instance progression, particularly in scaled deployments.

* Distributes workload evenly across Process Engine instances
* Facilitates redistribution during scale-up and scale-down
* Prevents process instances from getting stuck if a worker pod fails
* Performs cleanup tasks and monitors worker pod status

**Data stores:** PostgreSQL (`advancing`), Redis

<Card title="Advancing Controller" href="../platform-deep-dive/core-components/advancing-controller" icon="forward" />

### Events Gateway

The **Events Gateway** centralizes real-time communication between backend services and frontend clients through Server-Sent Events (SSE).

* Routes and distributes messages from Kafka topics to appropriate frontend clients
* Enables real-time UI updates without page refreshes or polling
* Uses Redis pub/sub to ensure messages reach the correct instance holding the SSE connection

<Card title="Events Gateway" href="../platform-deep-dive/core-components/events-gateway" icon="tower-broadcast" />

### Scheduler Core

The **Scheduler Core** handles time-based operations within processes.

* Sets process expiration dates and reminders
* Triggers time-based events and activities
* Manages recurring tasks and delayed actions

**Data stores:** MongoDB (`notification` shared with Notification Plugin)

<Card title="Scheduler Core" href="../platform-deep-dive/core-extensions/scheduler" icon="clock" />

***

## Application Lifecycle layer

The Application Lifecycle layer manages the full journey from design through build to deployment.

### Application Manager

The **Application Manager** handles project lifecycle management.

* Creates, updates, and deletes projects and their resources
* Manages versions, manifests, and configurations
* Serves as a proxy for frontend resource requests
* Handles project builds and deployments

**Data stores:** PostgreSQL (`app_manager`), MongoDB (`app-runtime`), S3 (`applications-bucket`)

<Card title="Projects" href="../projects" icon="folder-open" />

### Runtime Manager

The **Runtime Manager** works alongside the Application Manager to deploy and manage applications in runtime environments.

* Deploys application builds to runtime environments
* Manages runtime configurations and environment-specific settings
* Monitors and manages active application instances

### Admin

The **Admin** service manages process definitions and platform-wide settings.

* Stores and edits process definitions and data models
* Manages user roles and permissions
* Configures system-wide settings

**Data stores:** PostgreSQL (`flowxadmin`), MongoDB (`data-model`)

### Data Sync

The **Data Sync** job coordinates database migrations and data synchronization across multiple services.

* Manages Liquibase migrations for `app_manager`, `auth_system`, and `process_engine` databases
* Synchronizes resource definitions across MongoDB instances (CMS, Scheduler, Task Management, Document Plugin, Notification Plugin, Integration Designer)

***

## Content & Data layer

The Content & Data layer handles taxonomies, search, data persistence, and external system integrations.

### CMS Core

The **CMS Core** (Content Management System) manages all taxonomies and structured content within the platform.

* Manages enumerations, dropdown options, and categories
* Stores and serves localization content and translations
* Organizes media assets and reference data

**Data stores:** MongoDB (`cms-core`), S3 (`media-library-bucket`, `cms-private-storage-bucket`)

<Card title="Content Management" href="../platform-deep-dive/core-extensions/content-management/content-management" icon="folder-grid" />

### Data Search

The **Data Search** service enables search capabilities across process instances using Elasticsearch.

* Indexes process data automatically on status changes or at configured trigger points
* Supports filtering by process status, date ranges, and indexed keys
* Enables cross-application data discovery

**Data stores:** Elasticsearch (process instance index)

<Card title="Data Search" href="../platform-deep-dive/core-extensions/search-data-service" icon="magnifying-glass" />

### NoSQL DB Runner

The **NoSQL DB Runner** powers the FlowX Database feature, which stores structured data independently of process instances.

* Executes MongoDB operations (find, insert, update, delete)
* Supports both native MongoDB and Azure Cosmos DB (MongoDB API)
* Enables data sharing between different process instances

**Data stores:** MongoDB (`nosql-db-runner`)

<Card title="FlowX Database" href="../platform-deep-dive/integrations/flowx-database" icon="database" />

### Integration Designer

The **Integration Designer** provides a visual interface for creating and managing integrations with external systems.

* Defines REST API endpoints and authentication methods
* Creates and configures integration workflows with parallel branches
* Maps data between FlowX.AI processes and external systems
* Supports AI nodes for text, document, image, and data processing

**Data stores:** MongoDB (`integration-designer`), S3 (`workflows-bucket`)

<Card title="Integration Designer" href="../platform-deep-dive/integrations/integration-designer" icon="ruler-combined" />

***

## Authorization & Security layer

The Authorization & Security layer provides multi-tenant access control, workspace isolation, and identity management.

### Authorization System

The **Authorization System** is the centralized authorization service for the platform.

* Manages workspaces, users, groups, roles, and permissions
* Enforces access control lists (ACLs) for fine-grained resource permissions
* Provides RBAC (role-based access control) at organization, workspace, and project levels

**Data stores:** PostgreSQL (`auth_system`), SpiceDB (ACL operations)

### SpiceDB

**SpiceDB** is an embedded relationship-based access control (ReBAC) engine inspired by Google's Zanzibar paper.

* Stores and evaluates authorization policies
* Provides consistent, fine-grained permission decisions across all platform services
* Supports reverse lookups (finding all resources a user can access)

<Info>
  SpiceDB is an embedded component shipped with the platform. It runs alongside other services and is not deployed separately.
</Info>

### Organization Manager

The **Organization Manager** handles organization and tenant lifecycle management.

* Manages organization creation and provisioning
* Handles user registration and onboarding
* Monitors platform component health
* Publishes organization lifecycle events to Kafka

**Data stores:** PostgreSQL (`org_manager`)

### Multi-tenancy and workspaces

FlowX.AI uses **workspaces** to provide logical data isolation across the platform. Each workspace operates independently with its own resources (projects, libraries, themes) and access controls. The Authorization System, SpiceDB, and Organization Manager work together to enforce tenant boundaries while allowing users to belong to multiple workspaces.

<Card title="Workspaces" href="../projects/workspaces" icon="building" />

### Identity providers

FlowX.AI delegates authentication to external identity providers. Every request passes through the API Gateway, which validates OAuth2 tokens before allowing access.

<CardGroup>
  <Card title="Keycloak" href="../../setup-guides/access-management/configuring-an-iam-solution" icon="key" />

  <Card title="Azure AD (Entra)" href="../../setup-guides/access-management/configuring-an-iam-solution-entra" icon="key" />
</CardGroup>

***

## Business services

Business services extend the core engine with domain-specific capabilities. Document, Notification, and Task Management are deployed as core backend services alongside the engine; OCR and Reporting are formal plugins that ship through the Plugins versioning track.

### Document

Handles document generation and management.

* Generates documents from HTML templates
* Supports file upload, conversion, splitting, combining, and encryption/decryption
* Manages document storage and retrieval

**Data stores:** PostgreSQL (`document`), MongoDB (`document`, `app-runtime` read), S3 (`flowx-dev-bucket`, `temp-bucket`)

### Notification

Manages notifications across multiple channels.

* Sends email, SMS, and push notifications
* Handles OTP (one-time password) generation and validation
* Supports notification templates with dynamic content substitution

**Data stores:** MongoDB (`notification`, `app-runtime` read), S3 (`flowx-dev`)

### Task Management

Handles human task assignment and lifecycle.

* Manages task creation, assignment, and completion
* Supports allocation rules and out-of-office delegation
* Provides multi-language localization with substitution tags

**Data stores:** PostgreSQL (`process_engine` shared), MongoDB (`task-management-plugin`, `app-runtime` read)

<Card title="Task Management" href="../platform-deep-dive/core-extensions/task-management/task-management-overview" icon="list-check" />

### OCR (plugin)

The **OCR Plugin** provides optical character recognition for document processing and data extraction.

### Reporting (plugin)

The **Reporting Plugin** powers analytics and dashboards, integrating with Apache Superset for visualization.

<Card title="Plugins" href="../platform-deep-dive/plugins/custom-plugins" icon="plug" />

***

## Supporting Services

Supporting services provide cross-cutting capabilities like auditing, email communication, and licensing.

### Audit Core

The **Audit Core** service provides a centralized audit trail for all platform activities.

* Logs user actions and system events with timestamps, subjects, and status
* Stores audit data in Elasticsearch for efficient querying
* Ingests events from Kafka topic `ai.flowx.core.trigger.save.audit.v1`

**Data stores:** Elasticsearch (audit index)

<Card title="Audit" href="../platform-deep-dive/core-extensions/audit" icon="clipboard-list" />

### Email Gateway

The **Email Gateway** handles email communication workflows.

* Sends emails via SMTP and receives emails via IMAP
* Monitors configured mailboxes and publishes incoming email events to Kafka for process triggering
* Supports leader election for high availability across distributed instances

**Data stores:** PostgreSQL (`email_gateway`), MongoDB (`app-runtime` read)

### File Gateway

The **File Gateway** handles file-transfer integrations with external storage systems.

* Connects to FTP, SFTP, S3, and Azure Blob storage to ingest files into workflows and deliver generated artifacts back
* Polls watched locations for new files, uploads them to the Document service, and publishes Kafka events to start processes (file triggers)
* Supports distributed leasing for high availability across instances, mirroring the Email Gateway

**Data stores:** MongoDB (`file-gateway` collections, `app-runtime` read)

### AI Gateway

The **AI Gateway** powers the AI chat experience in the FlowX Designer.

* Streams AI assistant responses to the Designer in real time via Server-Sent Events (SSE)
* Routes chat requests to the config-time agents and manages conversation context
* Enforces workspace-level access control on AI interactions

**Data stores:** MongoDB, SpiceDB (ACL operations)

### License

The **License** service (formerly known as the License Engine) manages platform and application licensing, subscription plans, feature quotas, and usage tracking for FlowX organizations across SaaS and self-hosted deployments.

For setup and configuration, see [License service setup](/5.9/setup-guides/license-engine-setup).

**Data stores:** PostgreSQL (`license`)

***

## AI Platform

The **AI Platform** extends FlowX.AI with intelligent agents that operate at two levels:

* **Config-time agents** — embedded in the FlowX Designer to help developers and analysts build apps faster (AI Analyst, AI Designer, AI Developer, AI Assistant)
* **Business agents** — power end-user experiences at runtime, built with the Agent Builder or installed from the Agentic Apps Marketplace

In 5.9.0, the AI Platform comprises 10 services — `di-platform`, `ai-platform-ai-developer`, `ai-platform-planner`, `ai-platform-ai-analyst`, `ai-platform-ai-designer`, `ai-platform-agent-builder`, `ai-platform-ai-assistant`, `embedder`, `knowledgebase-rag`, and `knowledgebase-indexer-v2` — plus the **Observatory** stack (`observatory-api`, `observatory-web`, `observatory-guards`) for AI observability and governance. Vector storage and retrieval are handled by **Qdrant** (embedded).

### Standalone AI services

A separate set of AI-adjacent services ships from their own repositories rather than the AI Platform monorepo. They are not part of the AI Platform umbrella and install via separate paths:

* **doc-parser** — document parsing engine (PDF, DOCX, XLSX, PPTX, images; supports Tesseract, RapidOCR, EasyOCR; semantic chunking for RAG; signature detection; table extraction)
* **doc-converter** — document format conversion
* **web-crawler** — web content ingestion for the Web Page Extractor node
* **data-privacy** — PII detection and redaction (PII Guard)
* **speech-to-text** — audio transcription for voice and call workflows
* **evals-judge** — LLM-as-judge evaluation service for scoring agent and model outputs
* **modpod** — supporting runtime service

<Card title="AI Platform" href="../../ai-platform/ai-in-flowx" icon="hand-sparkles" />

***

## Client SDKs

The FlowX.AI SDKs provide process renderers that display dynamic UIs and orchestrate user interactions on each platform. The SDK architecture uses a framework-agnostic core (`@flowx/core-sdk`) with platform-specific wrappers.

<CardGroup>
  <Card title="Angular SDK" icon="code" href="../../sdks/angular-renderer">
    `@flowx/angular-sdk` for Angular applications
  </Card>

  <Card title="React SDK" icon="code" href="../../sdks/react-renderer">
    `@flowx/react-sdk` for React applications
  </Card>

  <Card title="React Native SDK" icon="code" href="../../sdks/react-native-renderer">
    Renderer for React Native applications
  </Card>

  <Card title="iOS SDK" icon="apple" href="../../sdks/ios-renderer">
    Native iOS renderer
  </Card>

  <Card title="Android SDK" icon="robot" href="../../sdks/android-renderer">
    Native Android renderer
  </Card>
</CardGroup>

<Note>
  The SDKs include companion packages for theming (`@flowx/ui-theme`) and UI components (`@flowx/ui-toolkit`).
</Note>

***

## Service communication

The following diagram shows the typical request flow through the platform:

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Client app (SDK)
    participant GW as API Gateway
    participant Engine as Process Engine
    participant Kafka as Kafka
    participant Plugin as Plugin / Integration
    participant Events as Events Gateway

    Client->>GW: Start process (REST + OAuth2 token)
    GW->>Engine: Forward authenticated request
    Engine->>Kafka: Publish process event
    Kafka->>Plugin: Route to plugin or integration
    Plugin->>Kafka: Return result event
    Kafka->>Engine: Deliver result
    Engine->>Kafka: Publish UI update event
    Kafka->>Events: Route SSE event
    Events->>Client: Push real-time update (SSE)
```

1. **Client applications** initiate processes through the API Gateway using REST calls with an OAuth2 token
2. The **Process Engine** executes the process definition and publishes events to Kafka
3. **Plugins and integrations** consume events, perform their work, and publish results back to Kafka
4. The **Events Gateway** picks up UI update events and pushes them to connected clients via SSE

This event-driven approach enables the platform to handle long-running processes asynchronously, keeping the user experience responsive while external systems process requests in the background.

***

## Service quick reference

| Service                       | Layer           | Port  | Primary DB          | Key Dependencies                    |
| ----------------------------- | --------------- | ----- | ------------------- | ----------------------------------- |
| **Process Engine**            | Core Engine     | 8085  | PostgreSQL, MongoDB | Kafka, Redis, Elasticsearch         |
| **Advancing Controller**      | Core Engine     | 8097  | PostgreSQL          | Redis, Process Engine               |
| **Events Gateway**            | Core Engine     | 8090  | —                   | Redis, Kafka                        |
| **Scheduler Core**            | Core Engine     | 8091  | MongoDB             | Kafka                               |
| **Application Manager**       | App Lifecycle   | 8099  | PostgreSQL, MongoDB | S3                                  |
| **Runtime Manager**           | App Lifecycle   | —     | —                   | Application Manager                 |
| **Admin**                     | App Lifecycle   | 8086  | PostgreSQL, MongoDB | —                                   |
| **Data Sync**                 | App Lifecycle   | —     | —                   | PostgreSQL (3 DBs), MongoDB (8 DBs) |
| **CMS Core**                  | Content & Data  | 8087  | MongoDB             | S3                                  |
| **Data Search**               | Content & Data  | 8096  | Elasticsearch       | Kafka                               |
| **NoSQL DB Runner**           | Content & Data  | 8121  | MongoDB             | —                                   |
| **Integration Designer**      | Content & Data  | 8098  | MongoDB             | S3                                  |
| **Authorization System**      | Auth & Security | 8100  | PostgreSQL          | SpiceDB                             |
| **SpiceDB**                   | Auth & Security | 50051 | (embedded)          | PostgreSQL                          |
| **Organization Manager**      | Auth & Security | 8102  | PostgreSQL          | SpiceDB                             |
| **Document Plugin**           | Plugins         | 8088  | PostgreSQL, MongoDB | S3                                  |
| **Notification Plugin**       | Plugins         | 8089  | MongoDB             | S3                                  |
| **Task Management**           | Plugins         | 8093  | PostgreSQL, MongoDB | —                                   |
| **OCR Plugin**                | Plugins         | —     | —                   | —                                   |
| **Audit Core**                | Supporting      | 8095  | Elasticsearch       | Kafka                               |
| **Email Gateway**             | Supporting      | —     | PostgreSQL, MongoDB | Kafka                               |
| **File Gateway**              | Supporting      | —     | MongoDB             | Kafka, Document                     |
| **AI Gateway**                | Supporting      | —     | MongoDB             | SpiceDB, AI Platform                |
| **License**                   | Supporting      | 8105  | PostgreSQL          | —                                   |
| **Document Parser**           | AI Platform     | —     | —                   | Kafka, AI providers                 |
| **AI Platform (10 services)** | AI Platform     | —     | Qdrant              | Kafka, AI providers                 |
| **FlowX Designer**            | Client          | —     | —                   | API Gateway                         |
| **Web / Mobile SDKs**         | Client          | —     | —                   | API Gateway, Events Gateway         |

<Tip>
  For detailed database names, S3 bucket names, and per-service operations (read/write), see the [Data architecture](./data-architecture) page.
</Tip>

***

## Infrastructure

FlowX.AI requires the following infrastructure components:

* **PostgreSQL / Oracle** — system of record for process definitions, instance state, and platform configuration
* **MongoDB** — document storage for runtime configuration, workflow state, and flexible data structures
* **Redis** — in-memory cache for process definitions, compiled scripts, and distributed locks
* **Apache Kafka** — event streaming backbone for all inter-service communication
* **Elasticsearch** — search indexes for process data and audit logs
* **S3-compatible storage** — files, documents, and binary assets
* **Qdrant** — vector database for the AI Platform RAG path (client-provisioned)

All services are containerized and designed for Kubernetes deployment. Stateless components support horizontal scaling, and Kafka provides resilient message handling across scaled instances.

<CardGroup>
  <Card title="Data architecture" href="./data-architecture" icon="database">
    Database-to-service mapping and storage details
  </Card>

  <Card title="Third-party components" href="../platform-deep-dive/third-party-components" icon="cube">
    Supported versions and compatibility matrix
  </Card>
</CardGroup>

***

## Quick demo

<video />

***

## Related resources

<CardGroup>
  <Card title="Data architecture" href="./data-architecture" icon="database">
    Database-to-service mapping, storage types, and sizing guidance
  </Card>

  <Card title="Third-party components" href="../platform-deep-dive/third-party-components" icon="cube">
    Supported versions and compatibility matrix
  </Card>

  <Card title="AI Platform" href="../../ai-platform/ai-in-flowx" icon="hand-sparkles">
    AI agents for config-time and runtime
  </Card>

  <Card title="SDKs overview" href="../../sdks/sdks-overview" icon="cubes">
    Web and mobile SDK documentation
  </Card>
</CardGroup>


# Intro to BPMN
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn

A process represents your business use case, such as requesting a credit card, placing a food order, or registering a vehicle.

To design and model process flows, we use the standard **BPMN 2.0** graphical representation.

## What is Business Process Model and Notation (BPMN)?

Business Process Model and Notation (BPMN) is a graphical representation for specifying business processes in a business process model.

It is **the most widely used standard for business process diagrams**. It is intended to be used directly by the stakeholders who design, manage and realize business processes, but at the same time be precise enough to allow BPMN diagrams to be translated into software process components.

This is why we chose it for modeling the process flows.

## BPMN 2.0 elements

A BPMN business process flow is represented as a set of process elements connected by sequences. Here are the most common types of elements:

<CardGroup>
  <Card title="Events" icon="bell" href="#events" />

  <Card title="Activities" icon="briefcase" href="#activities" />

  <Card title="Gateways" icon="code-branch" href="#gateways" />

  <Card title="Pools and lanes" icon="layer-group" href="#pools-and-lanes" />
</CardGroup>

### Events

Events describe something that happens during the course of a process. There are three main events types: start events, intermediate events, and end events. These three types are also defined as either catching events (they react to a trigger) or throwing events (they are triggered by the process).

<Frame>
  ![basic event types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/events.png)
</Frame>

### Activities

An activity represents a unit of work to be performed by the business process. An activity can be atomic (a task) or can represent a group of more activities (a subprocess).

<Frame>
  ![various types of activities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/activities.png)
</Frame>

### Gateways

Gateways are used to control how a process flows. They act as a decision point that picks which sequence flow should the [**process instance**](../../../projects/runtime/active-process/process-instance) take. This is based on the result of the evaluation of condition(s) specified (in case of exclusive gateways) or they can be used to split a process into more branches (in case of parallel gateways).

<Frame>
  ![exclusive and parallel gateways](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/gateways.png)
</Frame>

### Pools and lanes

Pools and lanes group the process steps by process participants. To show that certain user roles are responsible for performing specific process steps you can divide the process using lanes.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/swimlanes_pool.png)
</Frame>

## BPMN basic concepts

Let's get into a bit more details on the main types of BPMN process elements.

### Events

Events are signals that something happens within a process, including its start and end and any interactions with the process environment.

Types of Events:

* Start Events
* End Events
* Intermediate Events

### Start and End events

**Start & End events**

|                                                                                    Start Event Icon                                                                                    |                                                                                    End Event Icon                                                                                    |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/event_start.png) | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/event_end.png) |
|                                                                             Event that triggers the process                                                                            |                                                               Event that defines the state that terminates the process                                                               |

### Intermediate events

An intermediate event occurs between a start and an end event. It is represented by a circle with a double line, indicating its ability to both catch and throw information.

#### 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.

### Activities

#### Task

An atomic activity within a process flow, created when the activity cannot be broken down further. A task belongs to one lane.

|                                                                                          User task                                                                                          |                                                                                          Service task                                                                                          |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/user_task.png#center) | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/service_task.png#center) |
|                                                                              A task that requires human action                                                                              |                                             A task that uses a web service, automated application, or other kinds of service in completing the task                                            |

#### User Task

A task performed by the user without aid from a business process execution engine or application, requiring a certain action in the application.

#### Service Task

Executed by a business process engine. The task defines a script that the FlowX Engine can interpret and execute, completing when the script finishes. It can also run a [**business rule**](../../../building-blocks/actions/business-rule-action/business-rule-action) on the process data.

### BPMN Subprocesses

In BPMN, a subprocess is a compound activity that represents a collection of other tasks and subprocesses. Generally, we create BPMN diagrams to communicate processes with others. To facilitate effective communications, we really do not want to make a business process diagram too complex. By using subprocesses, you can split a complex process into multiple levels, which allows you to focus on a particular area in a single process diagram.

### Gateways

Gateways allow to control as well as merge and split the **process flow**.

#### Exclusive gateways

In business processes, you typically need to make choices — **business decisions**. The most common type of decision is choosing **either/or**. Exclusive Gateways limit the possible outcome of a decision to a single path, and circumstances choose which one to follow.

#### Parallel gateways

In many cases, you want to split up the flow within your business process. For example the sales and risk departments may examine a new mortgage application at the same time. This reduces the total cycle time for a case. To express parallel flow in BPMN, you use a **parallel gateway**.

|                                                                      Exclusive gateway (XOR)                                                                      |                                                                      Parallel gateway (AND)                                                                      |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/gateway_exclusive.png#center) | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/gateway_parallel.png#center) |
|                                                             <ul><li>defines a decision point</li></ul>                                                            |                                         <ul><li>no decision making </li><li>all outgoing branches are activated</li></ul>                                        |

**Closing gateway**

* Closes gateways by connecting branches with no logic involved
* The symbol used is determined by the initial gateway type.
* Parallel gateways:
  * These gateways wait for all input tokens and merge them into a single token.
  * Are aware of all preceding token flows, know the paths selected, and expect tokens from these paths.

## In depth docs

<Card title="BPMN Quick guide" icon="link" href="https://www.bpmnquickguide.com/view-bpmn-quick-guide/" />

<Card title="BPMN Best practices" icon="link" href="https://bpmtips.com/interview-with-sandeep-johal-process-modeling-best-practices/" />

For comprehensive insights into BPMN and its various node types, explore our course at FlowX Academy:

<Card title="BPMN 101" href="https://academy.flowx.ai/explore/bpmn-101" icon="school">
  * What's BPMN (Business Process Model Notation) and how does it work?
  * How is BPMN used in FlowX?
</Card>


# Intro to Elasticsearch
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch

Integrate Elasticsearch into event-driven architectures and workflows to efficiently index and search event data.

This integration allows event-driven systems to use Elasticsearch’s search and analytics capabilities for real-time processing and retrieval of event data.

## What is Elasticsearch?

Elasticsearch is a highly scalable open-source search and analytics engine built on top of the [Apache Lucene](https://lucene.apache.org/) library. It is designed to handle a wide range of data types and is particularly well-suited for real-time search and data analysis use cases. Elasticsearch provides a distributed, document-oriented architecture, making it capable of handling large volumes of structured, semi-structured, and unstructured data.

## How it works?

At its core, Elasticsearch operates as a distributed search engine, allowing you to store, search, and retrieve large amounts of data in near real-time. It uses a schema-less JSON-based document model, where data is organized into indices, which can be thought of as databases. Within an index, documents are stored, indexed, and made searchable based on their fields. Elasticsearch also provides advanced querying capabilities, allowing you to perform complex searches, filter data, and aggregate results.

## Why it is useful?

One of the key features of Elasticsearch is its distributed nature. It supports automatic data sharding, replication, and node clustering, which enables it to handle massive amounts of data across multiple servers or nodes. This distributed architecture provides high availability and fault tolerance, ensuring that data remains accessible even in the event of hardware failures or network issues.

Elasticsearch integrates with various programming languages and frameworks through its comprehensive RESTful API. It also provides official clients for popular languages like Java, Python, and JavaScript, enabling you to interact with the search engine in your preferred development environment.

## Indexing & sharding

### Indexing

Indexing refers to the process of adding, updating, or deleting documents in Elasticsearch. It involves taking data, typically in JSON format, and transforming it into indexed documents within an index. Each document represents a data record and contains fields with corresponding values. Elasticsearch uses an inverted index data structure to efficiently map terms or keywords to the documents containing those terms. This enables fast full-text search capabilities and retrieval of relevant documents.

### Sharding

Sharding, on the other hand, is the practice of dividing index data into multiple smaller subsets called shards. Each shard is an independent, self-contained index that holds a portion of the data. By distributing data across multiple shards, Elasticsearch achieves horizontal scalability and improved performance. Sharding allows Elasticsearch to handle large amounts of data by parallelizing search and indexing operations across multiple nodes or servers.

Shards can be configured as primary or replica shards. Primary shards contain the original data, while replica shards are exact copies of the primary shards, providing redundancy and high availability. By having multiple replicas, Elasticsearch ensures data durability and fault tolerance. Replicas also enable parallel search operations, increasing search throughput.

Sharding offers several advantages. It allows data to be distributed across multiple nodes, enabling parallel processing and faster search operations. It also provides fault tolerance, as data is replicated across multiple shards. Additionally, sharding allows Elasticsearch to scale horizontally by adding more nodes and distributing the data across them.

The number of shards and their allocation can be determined during index creation or modified later. Consider factors such as the size of the dataset, hardware resources, and search performance requirements when deciding on the number of shards.

For more details, check Elasticsearch documentation:

<Card icon="link" title="Elasticsearch documentation" href="https://www.elastic.co/guide/index.html" />

## Using Elasticsearch for advanced indexing with FlowX.AI

The integration between FlowX.AI and Elasticsearch involves the indexing of specific keys or data from the [**UI Designer**](../../../building-blocks/ui-designer/) to [process definitions](../../../building-blocks/process/process-definition). The indexing process is initiated by the [FlowX Engine](../../../platform-deep-dive/core-components/flowx-engine) which sends the data to Elasticsearch, where data is then indexed in the "process\_instance" index.

There are two methods available for indexing data: Kafka and HTTP.

* **Kafka**: Data is sent to be indexed through a Kafka topic using the new strategy. Deploy the [**Kafka Connect with Elasticsearch Sink Connector**](../../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#kafka-connect) in the infrastructure to utilize this method.
* **HTTP**: Data is indexed by establishing a direct connection from the FlowX Engine to Elasticsearch. Use HTTP calls to connect directly from the FlowX Engine to Elasticsearch.

To ensure effective indexing of process instances' details, a crucial step involves defining a mapping that specifies how Elasticsearch should index the received messages. This mapping is essential as the process instances' details often have specific formats. The process-engine takes care of this by automatically creating an index template during startup if it doesn't already exist. The index template acts as a blueprint, providing Elasticsearch with the necessary instructions on how to index and organize the incoming data accurately. By establishing and maintaining an appropriate index template, the integration between FLOWX.AI and Elasticsearch can index and retrieve process instance information in a structured manner.

### Kafka transport strategy

[Kafka](../event-driven-architecture-frameworks/intro-to-kafka-concepts) transport strategy implies process-engine sending messages to a Kafka topic whenever there is data from a process instance to be indexed. Kafka Connect is then configured to read these messages from the topic and forward them to Elasticsearch for indexing.

This approach offers benefits such as fire-and-forget communication, where the process-engine no longer needs to spend time handling indexing requests. By decoupling the process-engine from the indexing process and leveraging Kafka as a messaging system, the overall system becomes more efficient and scalable. The process-engine can focus on its core responsibilities, while Kafka Connect takes care of transferring the messages to Elasticsearch for indexing.

To optimize indexing response time, Elasticsearch utilizes multiple indices created dynamically by the Kafka Connect connector. The creation of indices is based on the timestamp of the messages received in the Kafka topic. The frequency of index creation, such as per minute, hour, week, or month, is determined by the timestamp format configuration of the Kafka connector.

It's important to note that the timestamp used for indexing is the process instance's start date. This means that subsequent updates received for the same object will be directed to the original index for that process instance. To ensure proper identification and indexing, it is crucial that the timestamp of the message in the Kafka topic corresponds to the process instance's start date, while the key of the message aligns with the process instance's UUID. These two elements serve as unique identifiers for determining the index in which a process instance object was originally indexed.

For more details on how to configure process instance indexing through Kakfa transport, check the following section:

<CardGroup>
  <Card title="Configuring Elasticsearch indexing" href="../../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing" icon="file" />

  <Card title="Configuration guidelines" href="../../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/process-instance-indexing-config-guidelines" icon="file" />
</CardGroup>


# Intro to Kafka concepts
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts

Apache Kafka is an open-source distributed event streaming platform that can handle a high volume of data and enables you to pass messages from one end-point to another.

Kafka is a unified platform for handling all the real-time data feeds. Kafka supports low latency message delivery and gives a guarantee for fault tolerance in the presence of machine failures. It can handle many diverse consumers. Kafka is very fast, and performs 2 million writes/sec. Kafka persists all data to the disk, which essentially means that all the writes go to the page cache of the OS (RAM). This makes it very efficient to transfer data from a page cache to a network socket.

### Benefits of using Kafka

* **Reliability** − Kafka is distributed, partitioned, replicated, and fault-tolerant
* **Scalability** − Kafka messaging system scales without downtime
* **Durability** − Kafka uses Distributed commit log which means messages persist on disk as fast as possible
* **Performance** − Kafka has high throughput for both publishing and subscribing messages. It maintains a stable performance even though many TB of messages are stored.

## Key Kafka concepts

### Events

Kafka encourages you to see the world as sequences of events, which it models as key-value pairs. The key and the value have some kind of structure, usually represented in your language’s type system, but fundamentally they can be anything. Events are immutable, as it is (sometimes tragically) impossible to change the past.

### Topics

Because the world is filled with so many events, Kafka gives us a means to organize them and keep them in order: topics. A topic is an ordered log of events. When an external system writes an event to Kafka, it is appended to the end of a topic.

In FLOWX.AI, Kafka handles all communication between the [FlowX Engine](../../../platform-deep-dive/core-components/flowx-engine) and external plugins and integrations. It is also used for notifying running process instances when certain events occur.  More information about KAFKA configuration on the section below:

<Card title="FlowX Engine setup guide" href="../../../../setup-guides/flowx-engine-setup-guide/engine-setup" icon="gears" />

### Producer

A producer is an external application that writes messages to a Kafka cluster, communicating with the cluster using Kafka’s network protocol.

### Consumer

The consumer is an external application that reads messages from Kafka topics and does some work with them, like filtering, aggregating, or enriching them with other information sources.

<Card title="How to create a Kafka producer" href="../../../platform-deep-dive/integrations/creating-a-kafka-producer" icon="link" />

<Card title="How to create a Kafka consumer" href="../../../platform-deep-dive/integrations/creating-a-kafka-consumer" icon="link" />

## In-depth docs

<CardGroup>
  <Card icon="link" title="Kafka documentation" href="https://kafka.apache.org/intro" />

  <Card icon="link" title="How Kafka works" href="https://www.confluent.io/blog/apache-kafka-intro-how-kafka-works/" />
</CardGroup>


# Intro to Kubernetes
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kubernetes

Kubernetes is an open-source container orchestration platform that automates many of the manual processes involved in containerized application deployment, management, and scaling.

The purpose of Kubernetes is to orchestrate containerized applications to run on a cluster of hosts. **Containerization** enables you to deploy multiple applications using the same operating system on a single virtual machine or server.

Kubernetes, as an open platform, enables you to build applications using your preferred programming language, operating system, libraries, or messaging bus. To schedule and deploy releases, existing continuous integration and continuous delivery (CI/CD) tools can be integrated with Kubernetes.

## Benefits of using Kubernetes

* A proper way of managing containers
* High availability
* Scalability
* Disaster recovery

## Key Kubernetes concepts

### Node & PODs

A Kubernetes node is a machine that runs containerized workloads as part of a Kubernetes cluster. A node can be a physical machine or a virtual machine, and can be hosted self-hosted or in the cloud.

A pod is composed of one or more containers that are colocated on the same host and share a network stack as well as other resources such as volumes. Pods are the foundation upon which Kubernetes applications are built.

Kubernetes uses pods to run an instance of your application. A pod represents a single instance of your application.

Pods are typically ephemeral, disposable resources. Individually scheduled pods miss some of the high availability and redundancy Kubernetes features. Instead, pods are deployed and managed by Kubernetes *Controllers*, such as the Deployment Controller.

### Service & Ingress

**Service** is an abstraction that defines a logical set of pods and a policy for accessing them. In Kubernetes, a Service is a REST object, similar to a pod. A Service definition, like all REST objects, can be POSTed to the API server to create a new instance. A Service object's name must be a valid [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt) label name.

**Ingress** is a Kubernetes object that allows access to the Kubernetes services from outside of the Kubernetes cluster. You configure access by writing a set of rules that specify which inbound connections are allowed to reach which services. This allows combining all routing rules into a single resource.

**Ingress controllers** are pods, just like any other application, so they’re part of the cluster and can see and communicate with other pods.  An Ingress can be configured to provide Services with externally accessible URLs, load balance traffic, terminate SSL / TLS, and provide name-based virtual hosting. An Ingress controller is in charge of fulfilling the Ingress, typically with a load balancer, but it may also configure your edge router or additional frontends to assist with the traffic.

FlowX.AI offers a predefined NGINX setup as Ingress Controller. The [NGINX Ingress Controller](https://www.nginx.com/products/nginx-ingress-controller/) works with the [NGINX](https://www.nginx.com/resources/glossary/nginx/) web server (as a proxy). For more information, check the below sections:

<Card title="Intro to NGINX" href="./intro-to-nginx" />

<Card title="FlowX Designer setup guide" href="../../../../setup-guides/designer-setup-guide" />

### ConfigMap & Secret

**ConfigMap** is an API object that makes it possible to store configuration for use by other objects. A ConfigMap, unlike most Kubernetes objects with a spec, has `data` and `binaryData` fields. As values, these fields accept key-value pairs. The `data` field and `binaryData` are both optional. The data field is intended to hold UTF-8 strings, whereas the `binaryData` field is intended to hold binary data as base64-encoded strings.

<Info>
  The name of a ConfigMap must be a valid [DNS subdomain name](https://www.ietf.org/rfc/rfc1035.txt).
</Info>

**Secret** represents an amount of sensitive data, such as a password, token, or key. Alternatively, such information could be included in a pod specification or a container image. Secrets are similar to ConfigMaps but they are designed to keep confidential data.

### **Volumes**

A Kubernetes volume is a directory in the orchestration and scheduling platform that contains data accessible to containers in a specific pod. Volumes serve as a plug-in mechanism for connecting ephemeral containers to persistent data stores located elsewhere.

### **Deployment**

A deployment is a collection of identical pods that are managed by the Kubernetes Deployment Controller. A deployment specifies the number of pod replicas that will be created. If pods or nodes encounter problems, the Kubernetes Scheduler ensures that additional pods are scheduled on healthy nodes.

Typically, deployments are created and managed using `kubectl create` or `kubectl apply`. Make a deployment by defining a manifest file in YAML format.

## Kubernetes architecture

Kubernetes architecture consists of the following main parts:

* Control Plane (master)
  * kube-apiserver
  * etcd
  * kube-scheduler
  * kube-controller-manager
  * cloud-controller-manager
* Node components
  * kubelet
  * kube-proxy
  * Container runtime

## Install tools

### kubectl

`kubectl` makes it possible to run commands against Kubernetes clusters using the `kubectl` command-line tool. `kubectl` can be used to deploy applications, inspect and manage cluster resources, and inspect logs. See the `kubectl` [reference documentation ](https://kubernetes.io/docs/reference/kubectl/)for more information.

### kind

`kind` command makes it possible to run Kubernetes on a local machine. As a prerequisite, Docker needs to be installed and configured. What `kind` is doing is to run local Kubernetes clusters using Docker container “nodes”.

## In depth docs

<Card icon="link" title="Kubernetes documentation" href="https://kubernetes.io/docs/home/" />


# Intro to NGINX
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx

NGINX is a free, open-source, high-performance web server with a rich feature set, simple configuration, and low resource consumption that can also function as a reverse proxy, load balancer, mail proxy, HTTP cache, and many other things.

### How NGINX is working?

NGINX allows you to hide a server application's complexity from a front-end application. It uses an event-driven, asynchronous approach to create a new process for each web request, with requests handled in a single thread.

### Using NGINX with FlowX Designer

[**The NGINX Ingress Controller for Kubernetes**](https://kubernetes.github.io/ingress-nginx/) - `ingress-nginx` is an ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.

Ingress allows you to route requests to services based on the host or path of the request, centralizing a number of services into a single entry point.

The [ingress resource](https://www.nginx.com/products/nginx-ingress-controller/nginx-ingress-resources/) simplifies the configuration of **SSL/TLS** **termination**, **HTTP load-balancing**, and **layer routing**.

For more information, check the following section:

<Card title="Using NGINX as a K8s ingress controller" icon="link" href="https://www.nginx.com/resources/videos/using-nginx-as-a-kubernetes-ingress-controller" />

#### Integrating with FlowX Designer

FlowX Designer is using NGINX ingress controller for the following actions:

1. For routing calls to plugins
2. For routing calls to the [FlowX Engine](../../../platform-deep-dive/core-components/flowx-engine):

* Viewing current instances of processes running in the FlowX Engine
* Testing process definitions from the FlowX Designer - route the API calls and SSE communications to the FLOWX engine backend
* Accessing REST API of the backend microservice

3. For configuring the Single Page Application (SPA) - FlowX Designer SPA will use the backend service to manage the platform via REST calls

In the following section, you can find a suggested NGINX setup, the one used by FlowX.AI:

<Card title="Designer setup guide" href="../../../../setup-guides/designer-setup-guide" icon="gears" />

### Installing NGINX Open Source

For more information on how to install NGINX Open Source, check the following guide:

<Card title="NGINX Admin Guide" icon="link" href="https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source?_ga=2.31029759.1179818521.1651763502-1509066026.1651763502" />


# Intro to Redis
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis

Open-source, in-memory key-value data store used as a cache for fast access to frequently used data with sub-millisecond response times.

It is also used as a Pub/Sub messaging solution, allowing messages to be passed to channels and for all subscribers to that channel to receive that message. This feature enables information to flow quickly through the platform without using up space in the database as messages are not stored.

Redis offers a primary-replica architecture in a single node primary or a clustered topology. This allows you to build highly available solutions providing consistent performance and reliability. You can scale the cluster size up or down, allowing the cluster to adjust to any demands.

## In depth docs

<CardGroup>
  <Card title="Redis.io" icon="link" href="https://redis.io/" />

  <Card title="Redis overview" icon="link" href="https://www.tutorialspoint.com/redis/redis_overview.htm" />
</CardGroup>


# Projects
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/application

Projects group all resources and dependencies needed to implement an use case.

<Frame>
  ![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)
</Frame>

## Overview

A project groups resources that represent a project's entire lifecycle. It's not just a collection of processes; it's an organized container holding all dependencies required for that project, from themes and templates to integrations and other resources. Projects enable you to:

* Create Versions of a project to manage changes over time.
* Deploy Builds for consistent environments.
* Organize Resources to ensure clarity and reduce errors.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)
</Frame>

## Core features

<CardGroup>
  <Card title="Centralized Resource Management" icon="folder">
    Projects provide a single view of all resources referenced in a process, enabling you to manage everything from one central location. This approach reduces context-switching and keeps configuration focused.
  </Card>

  <Card title="Localization and Multi-Language Support" icon="globe">
    Projects support the definition of multiple locales, allowing you to handle regional content and settings. Enumerations, substitution tags, and media can be localized to meet specific environment requirements.
  </Card>

  <Card title="Version Control and Builds" icon="code-branch">
    Projects support a versioning mechanism that tracks changes to processes, resources, and configurations. The Project Version captures a snapshot of all included resources, while the Build consolidates everything into a deployable package. Each build contains only one version of a project, ensuring a consistent deployment.
  </Card>

  <Card title="Dependency Management" icon="line-columns">
    Projects can use Libraries, which act similarly to projects but are designed for resource sharing across projects. A library can contain reusable components like processes or templates that can be included in other projects. Dependencies between projects and libraries are managed carefully to ensure compatibility.
  </Card>
</CardGroup>

## Config

Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

<video />

## Project components

### Processes

* **Processes**: Process definitions that drive the project's core functionality and share a project's resources.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/process_definition.png)
</Frame>

<Card title="Processes" href="../../building-blocks/process/process-definition" icon="link" />

* **Subprocesses**: Processes that can be invoked within the main process. These can either be part of the same project or imported from a library set as a dependency for the project.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_subprocess.gif)
</Frame>

<Card title="Subprocesses" href="../../building-blocks/process/subprocess" icon="link" />

### Content Management System (CMS)

* **Enumerations**: Predefined sets of options or categories used across the project. These are useful for dropdown menus, filters, and other selection fields.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/enums_app.png)
</Frame>

<Card title="Enumerations" href="../../platform-deep-dive/core-extensions/content-management/enumerations" icon="file" />

* **Substitution tags**: Here you have system predefined substitution tags and dynamic placeholders that allow for personalized content, such as user-specific data in notifications or documents.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/subst_tags.png)
</Frame>

<Card title="Substitution tags" href="../../platform-deep-dive/core-extensions/content-management/substitution-tags" icon="page" />

* **Media Library**: A collection of images, videos, documents, and other media assets accessible within the project.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/media_library_app.png)
</Frame>

### Task Management

* **Views**: Views are configurable interfaces that present task-related data based on specific business process definitions. They allow users to create tailored visualizations of task information, utilizing filters, sorting options, and custom parameters to focus on relevant data.
* **Stages**: The phases that a task goes through within a workflow (e.g., Pending, In Progress, Completed).
* **Allocation Rules**: Criteria for assigning tasks within workflows based on predefined rules (e.g., user roles, availability).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/app_task_manager.gif)
</Frame>

### Integrations

* **Systems (API Endpoints)**: Configurations for connecting to external systems via REST APIs. These endpoints facilitate data exchange and integration with third-party platforms.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/systems_overview.png)
</Frame>

* **Workflows**: Workflows are configurable sequences of tasks and decision nodes that automate data processing, system interactions, and integrations, enabling efficient communication and functionality across different projects and services.

<video />

### Dependencies

Dependencies refer to the relationship between a project and the external resources it relies on, typically housed in a **Library**. These dependencies allow projects to access and utilize common assets, like processes, enumerations, or media files, from another project without duplicating content. By managing dependencies effectively, organizations can ensure that their projects remain consistent, efficient, and modular, streamlining both development and maintenance.

* **Libraries**: A library is a special type of project that stores reusable resources. Projects can declare a library as a dependency to gain access to the resources stored within it.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/libraries_dependencies.gif)
</Frame>

* **Build-Specific Dependencies**: When a a project adds a library as a dependency, it does so by referencing a specific build of that library

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/build_library.png)
</Frame>

<Info>
  This build-specific dependency ensures that changes in the library do not automatically propagate to the dependent projects, providing stability and control over which version is in use.
</Info>

* **Versioning**: Dependencies are versioned, meaning a project can rely on a particular version of a library's build. This versioning capability allows projects to remain insulated from future changes until they are ready to update to a newer version.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/library_build.gif)
</Frame>

<Card title="Libraries" href="libraries" icon="file">
  Read more about libraries by accessing this section
</Card>

***

### Configuration Parameters

Configuration Parameters are essential components that allow projects to be dynamic, flexible, and environment-specific. They provide a way to manage variables and values that are likely to change based on different deployment environments (e.g., Development, QA, Production), without requiring hardcoded changes within the project. This feature is particularly useful for managing sensitive information and environment-specific settings.

* **Set environment-specific values**: Tailor your project's behavior depending on the target environment.
* **Store sensitive data securely**: Store API keys, passwords, or tokens securely using environment variables.
* **Centralize settings**: Manage common values in one place, making it easier to update settings across multiple processes or integrations.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/config_params.png)
</Frame>

***

### Project level settings

#### Name

The name of the project, which serves as the main identifier for your project within FlowX AI. This name is used to categorize and manage all associated resources.

#### Type

You have two options:

* **Application**: A standard project that will contain processes, resources, integrations, and other elements.
* **Library**: A reusable set of resources that can be referenced by multiple projects.

#### Platform type

You can specify the platforms for the project:

* **Omnichannel**: The project will support web, mobile, and other platforms.
* **Web**: The project will be restricted to web-based access.
* **Mobile**: The project will only be accessible via mobile platforms.

#### Project entry point

The entry point declares **what the generic container app launches** when it loads your project version. Either a **Process** or a **UI Flow** can be set as the entry point, and the entry point applies in both configuration testing and runtime.

<Info>
  **Required to run your project from the generic container app.** Without an entry point, the container app loads the project shell but has nothing to render — users see an empty screen. Set the entry point before sharing the container app URL with end users or test runners.
</Info>

**Setting the entry point.** Open **Project Settings → General** and pick the resource under **Project Entry Point**:

* For **Web** platforms, set the **Web** entry point.
* For **Mobile** platforms, set the **Mobile** entry point.
* For **Omnichannel** projects, set both — each platform launches its own entry point.

Only project-type entries can have entry points; **library** projects do not. The dropdown lists every Process and UI Flow defined inside the current project version, grouped by resource type.

<Tip>
  Changing the entry point takes effect on the next build. Verify the change by re-running the project in the container app after committing a new build.
</Tip>

#### Default theme

Choose a theme to apply a consistent look and feel across the project. Themes manage colors, fonts, and UI elements for a unified visual experience. In the screenshot, "FlowXTheme" is selected as the default.

<Card title="Theming" href="" icon="page" />

#### Number formatting

* **Min Decimals** and **Max Decimals**: Configure how numbers are displayed in the project by setting the minimum and maximum decimal points. This helps ensure data consistency when dealing with financial or scientific information.
* **Date Format**: Choose the format for displaying dates (e.g., short or long formats) to ensure the information is localized or standardized based on your project's requirements.
* **Currency Format**: Set whether currency is displayed using the ISO code (e.g., USD) or using a symbol (\$). This affects how financial information is presented across the project.

#### Languages

This section allows you to manage languages supported by the project.

* **Default Language**: You can set one language as the default, which will be the primary language for users unless they specify otherwise. In the screenshot, English (EN) is set as the default language.
* **Add Multiple Languages**: This enables multi-language support. Substitution tags and enumerations can be localized to provide a better experience for users in different regions.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/app_settings.png)
</Frame>

Fore more information about localization and internationalization, check the following section:

<Card title="l10n & i18n" href="../../building-blocks/ui-designer/localization-and-i18n" icon="page" />

## Creating and managing projects

A project's lifecycle includes the following stages:

<Steps>
  <Step title="Creating a Project">
    * Start by defining the name and type (Omnichannel, Web, Mobile).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/create_first_app.gif)
    </Frame>

    * Set up initial configurations like themes, languages, and formats.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/configure_initial.gif)
    </Frame>

    * Inherit system-wide design assets like themes or fonts.
  </Step>

  <Step title="Configuring Resources">
    * Add processes, define templates, set up enumerations, and manage integrations.
    * Configure environment-specific parameters like API URLs or passwords using environment variables.
    * Reuse resources from libraries by setting up dependencies, allowing access to shared content.
  </Step>

  <Step title="Publishing a Project">
    * Submit your configured resources to a version.
    * Once finalized, a version can be committed for stability.
    * Create a build from a version when ready to deploy to a different environment.
  </Step>

  <Step title="Deploying a Build">
    * A build packages the project version for a consistent deployment.
    * Each build is immutable and cannot be modified once created, ensuring runtime stability.
  </Step>
</Steps>

<Frame>
  <video />
</Frame>

## FAQs

<AccordionGroup>
  <Accordion title="How do I create a new version of a project?">
    To create a new version, navigate to the project dashboard, select "Create New Version," and make any changes. Once finalized, commit the version to lock it.
  </Accordion>

  <Accordion title="What happens when I create a build?">
    Creating a build captures a snapshot of the project version, consolidating resources into a single deployable package. Builds are immutable and cannot be edited once created.
  </Accordion>

  <Accordion title="Can I manage multiple localizations within a project">
    Yes, projects support multiple locales. You can define regional settings, such as date formats and currencies, to cater to different environments.
  </Accordion>

  <Accordion title="How do I handle resource changes in a shared environment?">
    When modifying shared resources, FlowX AI enforces versioning. You can track which processes or resources are affected by a change and revert if necessary.
  </Accordion>

  <Accordion title="What is the difference between a Project Version and a Build?">
    A Project Version is a snapshot of resources and configurations that can be modified, tracked, and rolled back. A Build is a deployable package created from a committed version, and it is immutable once deployed.
  </Accordion>

  <Accordion title="How do I add a library as a dependency?">
    Go to your project settings, navigate to dependencies, and select the desired library. Choose the build you want to use, and its resources will be accessible within your project.
  </Accordion>

  <Accordion title="Can I make changes to a deployed build?">
    No, a build is immutable. To make changes, modify the project version, create a new version, and deploy a new build.
  </Accordion>

  <Accordion title="How are resource versions managed within a project?">
    Each resource has a Resource Definition ID (consistent across versions) and a Resource Version ID (specific to each version). These ensure that the correct version of a resource is used at runtime.
  </Accordion>

  <Accordion title="What is the purpose of dependencies in FlowX AI?">
    **A:** Dependencies allow projects to share and reuse resources like processes, enumerations, and templates that are stored in libraries. By setting a library as a dependency, a project can access the resources it needs without duplication, fostering modular development.
  </Accordion>

  <Accordion title="How do versioning and dependencies work together?">
    **A:** Dependencies are version-controlled, meaning you can choose specific library builds to ensure stability. Each build version of a library captures the state of its resources, allowing projects to lock onto a particular version until they are ready to upgrade.
  </Accordion>

  <Accordion title="Can I remove a dependency from a project?">
    **A:** Yes, you can remove a dependency from the project. Go to the **Dependencies** section in the project settings and select the dependency you want to remove. However, make sure that no critical resources in the project rely on that dependency.
  </Accordion>

  <Accordion title="What are the risks of circular dependencies?">
    **A:** Circular dependencies occur when two libraries depend on each other. This can lead to conflicts and unexpected behavior. It's best to keep dependencies modular and avoid tightly coupling libraries to prevent such issues.
  </Accordion>

  <Accordion title="How do I ensure that a library update doesn't break my project?">
    **A:** Use a controlled environment like Dev or UAT to test new builds of the library before updating the dependency in your main project. This allows you to validate changes and ensure they don't negatively impact your project.
  </Accordion>

  <Accordion title="What happens to resource versions when I update a dependency?">
    **A:** When a dependency is updated to a newer build, any resources that were modified in the library will reflect the latest version. Projects have control over when to update, so older versions remain stable until the dependency is manually updated.
  </Accordion>
</AccordionGroup>


# Dependencies
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/dependencies

Manage dependencies between projects and libraries to enable resource sharing, modular development, and version control across your FlowX applications

Dependencies in FlowX enable projects and libraries to share and reuse resources, fostering modular development and reducing duplication. By establishing dependency relationships, you can access common assets like processes, enumerations, and media files from external libraries while maintaining version control and stability.

## Overview

<Frame>
  ![Dependencies overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dependencies_ov.png)
</Frame>

Dependencies allow you to:

* **Share resources** across projects and libraries without duplication
* **Maintain version control** by referencing specific builds
* **Create modular architectures** with reusable components
* **Ensure stability** through controlled dependency management
* **Build hierarchical structures** with library-to-library dependencies

## Types of dependencies

<Tabs>
  <Tab title="Project Dependencies">
    **Project Dependencies** allow projects to reference and use resources from libraries.

    ### Key Features

    * **Library Access**: Projects can add libraries as dependencies to access their resources
    * **Build-Specific**: Dependencies reference specific builds of libraries for stability
    * **Version Control**: Projects control when to upgrade to newer library versions
    * **Resource Availability**: All resources from dependent libraries become available in the project

    ### Use Cases

    * Shared UI components and templates
    * Common business processes and subprocesses
    * Standardized enumerations and configuration
    * Reusable integration workflows

    <Frame>
      ![Project dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/projects_dependencies.png)
    </Frame>
  </Tab>

  <Tab title="Library Dependencies">
    **Library Dependencies** enable libraries to depend on other libraries, creating hierarchical dependency structures.

    ### Key Features

    * **Library-to-Library**: Libraries can now reference other libraries as dependencies
    * **Dependency Tree**: Create complex hierarchical structures with multiple levels
    * **Resource Inheritance**: Projects gain access to resources from the entire dependency hierarchy
    * **Modular Design**: Break down complex functionality into smaller, focused libraries

    ### Use Cases

    * Country-specific processes that use common base libraries
    * Shared utility libraries used by multiple specialized libraries
    * Hierarchical organization of business domains
    * Team-based development with library ownership

    <Frame>
      ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
    </Frame>
  </Tab>
</Tabs>

## Dependency tree management

### Understanding dependency trees

A **dependency tree** represents the hierarchical structure of dependencies for a project or library. In FlowX 5.1, dependency trees can include multiple levels of library dependencies.

<Frame>
  ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
</Frame>

#### Example dependency tree

```
Mortgage Project
├── Enums Library (1.6.0)
├── Integrations Library (2.5.0)
│   ├── Commons Library (1.1.0)  
│   └── Enums Library (1.6.0) # Transitive dependency
└── Subprocesses Library (1.3.0)
    └── Enums Library (1.6.0)  # Transitive dependency
```

### Dependency tree constraints

<Warning>
  **Important Constraint**: FlowX 5.1 implements a **single-version constraint** for dependency trees. The same library cannot exist multiple times in a dependency tree with different builds.
</Warning>

#### Allowed scenarios

<Accordion title="Same library, same version (Allowed)">
  ```
  Mortgage Project
  ├── Subprocesses Library (1.3.0)
  │   └── Enums Library (1.6.0)
  └── Integrations Library (2.4.0)
      └── Enums Library (1.6.0)  # ✅ Same version - ALLOWED
  ```

  This scenario is permitted because both references use the same build (1.5.0) of the Enums Library.
</Accordion>

#### Blocked scenarios

<Accordion title="Same library, different versions (Blocked)">
  ```
  Mortgage Project
  ├── Enums Library (1.6.0)           # Direct dependency
  └── Subprocesses Library (1.3.0)
      └── Enums Library (1.5.0)       # ❌ Different version - BLOCKED
  ```

  This scenario is **blocked** because it would create a version conflict in the dependency tree.
</Accordion>

<Accordion title="Circular dependencies (Blocked)">
  ```
  Library A (1.0.0)
  └── Library B (1.0.0)
      └── Library A (1.1.0)  # ❌ Circular reference - BLOCKED
  ```

  Circular dependencies are **strictly prohibited** to prevent infinite loops and maintain dependency tree integrity.
</Accordion>

### Conflict resolution

When dependency conflicts occur, you have several resolution options:

<Steps>
  <Step title="Update Direct Dependencies">
    Update the direct library dependency to a version that uses the required transitive dependency version.

    ```
    # Before (Conflict)
    Project → Library A (1.0) → Commons (1.1)
           → Library B (2.0) → Commons (1.2)  # Conflict

    # After (Resolved)
    Project → Library A (1.1) → Commons (1.2)  # Updated A to use Commons 1.2
           → Library B (2.0) → Commons (1.2)  # Now compatible
    ```
  </Step>

  <Step title="Create New Library Builds">
    Create new builds of libraries that include the required dependency versions.
  </Step>

  <Step title="Restructure Dependencies">
    Reorganize your dependency structure to avoid conflicts, potentially by creating intermediate libraries.
  </Step>
</Steps>

## Managing dependencies

### Adding project dependencies

<Steps>
  <Step title="Navigate to Dependencies">
    In your project workspace, go to the **Config** tab and select **Dependencies**.
  </Step>

  <Step title="Add Library Dependency">
    Click **Add Dependency** and select the library you want to add.

    <Frame>
      ![Add project dependency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/select_dependency.png)
    </Frame>
  </Step>

  <Step title="Select Build Version">
    Choose the specific build version of the library you want to use.

    <Warning>
      Only committed builds are available.
    </Warning>
  </Step>

  <Step title="Validate Dependency Tree">
    FlowX will automatically validate that the new dependency doesn't create conflicts in your dependency tree.
  </Step>

  <Step title="Confirm Addition">
    Review the dependency tree preview and confirm the addition. The library's resources will become available in your project.
  </Step>
</Steps>

### Adding library dependencies

<Steps>
  <Step title="Open Library Configuration">
    Navigate to your library and go to the **Config** tab, then select **Dependencies**.
  </Step>

  <Step title="Add Library Dependency">
    Click **Add Dependency** and select another library as a dependency.

    <Frame>
      ![Add library dependency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/add_lib_dependency.png)
    </Frame>
  </Step>

  <Step title="Conflict Detection">
    FlowX will check for potential conflicts, including:

    * Version conflicts with existing dependencies
    * Circular dependency detection
    * Transitive dependency validation
  </Step>

  <Step title="Review Dependency Tree">
    Preview the complete dependency tree to understand all transitive dependencies.
  </Step>
</Steps>

### Updating dependencies

<Accordion title="Single Dependency Update">
  When updating a single dependency:

  1. Navigate to the **Dependencies** section
  2. Select the dependency to update
  3. Choose the new build version
  4. FlowX validates the dependency tree for conflicts
  5. If conflicts exist, resolve them before proceeding

  <Frame>
    ![Update dependency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/single_dep_update.png)
  </Frame>
</Accordion>

<Accordion title="Bulk Dependency Updates">
  For complex dependency trees, you may need to update multiple dependencies simultaneously:

  1. Plan your update strategy to avoid intermediate conflicts
  2. Update dependencies in the correct order (typically from leaf to root)
  3. Use the dependency tree view to validate changes
  4. Test in a development environment before applying to production

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/bulk_dep_update.png)
  </Frame>
</Accordion>

## Resource resolution

### Resource types and references

Different resource types use different referencing mechanisms:

| Resource Type               | Reference Method       | Example                        |
| --------------------------- | ---------------------- | ------------------------------ |
| **Process**                 | Resource Definition ID | `proc_customer_onboarding_123` |
| **Media Library Item**      | Resource Definition ID | `media_logo_456`               |
| **System/Workflow**         | Resource Definition ID | `sys_crm_integration_789`      |
| **Enumeration**             | Name                   | `CUSTOMER_TYPES`               |
| **Substitution Tag**        | Name                   | `WELCOME_MESSAGE`              |
| **Notification Template**   | Name                   | `EMAIL_CONFIRMATION`           |
| **Document Template**       | Name                   | `CONTRACT_TEMPLATE`            |
| **Configuration Parameter** | Name                   | `MAX_RETRY_COUNT`              |

### Resource precedence rules

When multiple resources with the same name exist in the dependency tree:

<Steps>
  <Step title="Highest Level Wins">
    Resources from the **highest level** (closest to the project) take precedence.

    ```
    Project (Level 0)
    ├── Library A (Level 1) - contains ENUM_X
    └── Library B (Level 1)
        └── Library C (Level 2) - contains ENUM_X

    # ENUM_X from Library A (Level 1) is used
    ```
  </Step>

  <Step title="Same Level Resolution">
    If resources exist at the same level, the resource from the **newest build** (by build creation date) takes precedence.
  </Step>

  <Step title="Predictable Resolution">
    The resolution is deterministic and consistent across environments.
  </Step>
</Steps>

<Warning>
  **Best Practice**: Avoid duplicate resource names across libraries in your dependency tree to maintain control and predictability over resource usage at runtime.
</Warning>

## Build and deploy considerations

### Build export/import

When exporting or importing builds:

* **All dependent libraries** are included in the export package
* **Transitive dependencies** are automatically resolved and included
* **Version consistency** is maintained across environments
* **Dependency tree structure** is preserved during import

### Runtime behavior

At runtime:

* **Resource resolution** follows the established precedence rules
* **Dependency tree** is flattened for efficient resource lookup
* **Version consistency** ensures predictable behavior
* **Build immutability** guarantees that deployed builds remain stable

## Best practices

### Dependency design

<Check>
  **Keep dependencies modular**: Design libraries with clear, focused responsibilities to avoid monolithic structures.
</Check>

<Check>
  **Plan your hierarchy**: Design your dependency tree structure before implementation to avoid conflicts later.
</Check>

<Check>
  **Use semantic versioning**: Follow consistent versioning practices to make dependency management predictable.
</Check>

<Check>
  **Avoid circular dependencies**: Design your library architecture to prevent circular references.
</Check>

<Check>
  **Document dependencies**: Maintain clear documentation of library purposes and dependency relationships.
</Check>

### Version management

<Check>
  **Lock to specific builds**: Always reference specific builds rather than "latest" versions for stability.
</Check>

<Check>
  **Test dependency updates**: Use development environments to test dependency updates before production.
</Check>

<Check>
  **Plan upgrade paths**: Consider the impact on dependent projects when updating library versions.
</Check>

<Check>
  **Maintain backward compatibility**: When possible, maintain backward compatibility to ease library updates.
</Check>

### Team collaboration

<Check>
  **Establish ownership**: Clearly define which teams own which libraries to coordinate updates.
</Check>

<Check>
  **Communication protocols**: Establish processes for communicating library changes to dependent teams.
</Check>

<Check>
  **Shared standards**: Agree on naming conventions and design patterns across library-owning teams.
</Check>

## Troubleshooting

### Common dependency issues

<Accordion title="Version Conflict Errors">
  **Problem**: Cannot add dependency due to version conflicts.

  **Solutions**:

  * Update existing dependencies to compatible versions
  * Create new library builds with compatible dependency versions
  * Restructure your dependency hierarchy to avoid conflicts
  * Review your dependency tree for optimization opportunities
</Accordion>

<Accordion title="Circular Dependency Detection">
  **Problem**: System prevents adding a dependency due to circular reference.

  **Solutions**:

  * Analyze your dependency structure to identify the circular path
  * Extract common functionality into a separate base library
  * Restructure libraries to create a proper hierarchy
  * Consider if the circular dependency indicates a design issue
</Accordion>

<Accordion title="Missing Resources">
  **Problem**: Expected resources are not available after adding dependencies.

  **Solutions**:

  * Verify the dependency was added with the correct build version
  * Check if resources exist in the expected library build
  * Review resource name conflicts that might affect precedence
  * Ensure the library build contains the expected resources
</Accordion>

<Accordion title="Build Export Issues">
  **Problem**: Build export fails due to dependency problems.

  **Solutions**:

  * Validate all dependencies are using committed builds (not WIP)
  * Ensure all transitive dependencies are available
  * Check for missing or deleted library builds
  * Review access permissions for all dependent libraries
</Accordion>

## FAQ

<Accordion title="Can libraries depend on multiple other libraries">
  Yes, libraries can have multiple dependencies, just like projects. Each dependency is managed independently and contributes to the overall dependency tree.
</Accordion>

<Accordion title="What happens if I delete a library that others depend on?">
  FlowX prevents deletion of libraries that are referenced as dependencies. You must remove all dependency references before a library can be deleted.
</Accordion>

<Accordion title="Can I test with WIP versions of dependencies?">
  No, dependencies must reference committed builds, not WIP (Work in Progress) versions. This ensures stability and prevents issues with changing dependencies.
</Accordion>

<Accordion title="How deep can dependency trees go?">
  There's no enforced limit on dependency tree depth, but for maintainability and performance, it's recommended to keep trees reasonably shallow (typically 3-4 levels maximum).
</Accordion>

<Accordion title="What's the difference between direct and transitive dependencies?">
  * **Direct dependencies**: Libraries explicitly added as dependencies to your project or library
  * **Transitive dependencies**: Libraries that are dependencies of your direct dependencies (automatically included)
</Accordion>

<Accordion title="How do I resolve dependency conflicts between teams?">
  1. Establish clear communication channels between teams
  2. Plan library updates and coordinate with dependent teams
  3. Use development environments to test impact of changes
  4. Consider creating shared governance processes for critical libraries
</Accordion>

<Accordion title="Can I override a transitive dependency with a direct dependency?">
  No, FlowX enforces the single-version constraint. If you need a different version of a transitive dependency, you must update the direct dependency that includes it.
</Accordion>


# Libraries
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/libraries

Libraries are specialized projects that serve as reusable containers for resources that can be shared across multiple projects.

<Frame>
  ![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)
</Frame>

Unlike regular projects, which are intended for creating and managing specific workflows, libraries are designed to house common elements—like processes, enumerations, and media assets—that other projects may rely upon.

This makes libraries a cornerstone for establishing consistency and efficiency across various projects.

#### Key features

* **Resource Sharing**:

  * Libraries facilitate the reuse of resources like processes, enumerations, and media assets across different projects. This allows for a more modular design, where commonly used elements are stored centrally.
  * Resources in a library can be included in other projects by setting the library as a dependency.

* **Dependencies**:

  * A project can add a library as a dependency, meaning it will have access to the resources stored in that library.
  * Dependencies are managed through builds; each project can choose a specific version (build) of a library to depend on. This ensures that updates in the library do not automatically impact all projects unless intended.

* **Versioning**:

  * Just like projects, libraries can be versioned. Each version of a library captures the state of its resources at a specific point in time.
  * This versioning allows projects to lock dependencies to specific library versions, providing stability and predictability during runtime.

#### Managing libraries

1. **Creating a Library**:

   * Libraries can be created similarly to projects. The creation process involves setting a name, defining the resources it will contain, and managing its configuration settings.
   * Once created, resources can be added to the library incrementally, allowing for iterative development.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/docs_library.png)
</Frame>

2. **Managing Library Resources**:

   * Users can create, edit, delete, or version resources within the library. Resources include processes, enumerations, media files, and other elements that can be referenced by projects.
   * A library can have multiple versions, each capturing the resource state. This allows backward compatibility with older project builds relying on specific library versions.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/library_build.png)
</Frame>

3. **Adding Library Dependencies to Projects**:

   * In the project workspace, libraries can be set as dependencies under the **Dependencies** section.
   * Users can select which build version of the library to reference. This allows projects to control how library changes affect them by choosing to update the dependency to newer library builds as needed.

<Info>
  Libraries can be added as a dependency only to Work-In-Progress (WIP) project versions.
</Info>

<Frame>
  <video />
</Frame>

#### Library build process

* **Builds in Libraries** are tagged versions, allowing a snapshot of the current library resources to be used by projects. Each build in a library captures the state of all its resources.
* Projects referencing a library can specify the exact build to use, ensuring that changes to the library do not inadvertently impact dependent projects.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/library_build.gif)
</Frame>

#### Use cases

1. **Centralized Resource Management**:

   * Organizations that need to maintain a standard set of processes or other resources can use libraries to store these centrally. Each project can then use the same library resources, ensuring consistency.

2. **Version-Controlled Dependency Management**:

   * By utilizing builds and versioning within libraries, projects can safely depend on specific versions, reducing the risk of unexpected behavior due to resource updates.

3. **Streamlining Updates Across Projects**:

   * When an update is required across multiple projects that rely on the same resources, it can be done by updating the library and releasing a new build. Each project can then choose to update to the new build when ready.

## Best practices

* Use libraries for resources that need to be standardized across multiple projects.
* Carefully manage dependencies and choose specific builds to avoid unexpected runtime behavior.
* Use versioning to maintain a clear history of resource changes, allowing rollbacks if necessary.

Libraries thus play a crucial role in modularizing the development process, enabling reusable and maintainable components across different projects. This leads to improved project organization, reduced redundancy, and simplified resource management.

## FAQs

<AccordionGroup>
  <Accordion title="How do I add a library as a dependency to an project?">
    **A:** In the project workspace, navigate to the **Dependencies** section. Select the library you want to add, choose the specific build version, and confirm. Once added, the resources from that library will be available for use within the project.
  </Accordion>

  <Accordion title="What happens if a resource in a library is updated?">
    **A:** When a resource in a library is updated, dependent projects will not be affected unless the library build they reference is updated to a newer version. This allows projects to maintain stability by controlling when updates are adopted.
  </Accordion>

  <Accordion title="Can I use multiple libraries as dependencies for a single project?">
    **A:** Yes, a project can depend on multiple libraries. Each library can be referenced by selecting the desired build version. However, ensure that dependencies are managed carefully to avoid conflicts or redundancy.
  </Accordion>

  <Accordion title="What should I do if a newer library build is available?">
    **A:** Before switching to a newer library build, test it in a development or staging environment to ensure compatibility. If everything functions as expected, update the project’s dependency to the new build in the **Dependencies** section.
  </Accordion>
</AccordionGroup>


# Versioning
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/versioning

Easily track and manage your project's evolution with comprehensive versioning features.

Versioning enables you to manage changes, track progress, and collaborate effectively by capturing snapshots of your project's state at any point in time. The versioning system ensures that resources are grouped and tracked as part of the project, providing a comprehensive and structured approach to development.

## Project version

A **Project Version** is an editable snapshot of your project at a specific moment. It contains all resources (e.g., processes, integrations, templates) and configurations grouped under the project.

* **Project**: The main project entity that contains all your resources (processes, integrations, templates, etc.)
* **Project Branch**: Branches within a project (similar to Git branches) that allow parallel development
* **Project Version**: Individual versions within branches that track the state of your project

Each version can have one of the following statuses:

* **WIP (Work In Progress)**: Draft versions that are actively being edited
* **COMMITTED**: Finalized versions that have been submitted with a commit message
* **MERGE\_IN\_PROGRESS**: Versions currently being merged between branches

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-22%20at%2019.09.53.png)
</Frame>

The tab above provides a summary of all accessible project versions and branches available in the current environment.

<Info>
  Resources within a project (e.g., processes, integrations, templates) are versioned as part of the project, not individually.
</Info>

<Info>
  Certain resources are considered **global** and are not included in project-specific versioning. These resources are shared across projects and environments to maintain consistency and simplify their management. Examples of such global resources include:

  * **Themes**: Predefined design themes used across multiple projects.
  * **Fonts**: A library of fonts accessible globally.
  * **Global Media Files**: Shared media assets.
  * **Out of Office Settings**: Configurations for user availability and auto-responses that are managed at the platform level.
</Info>

***

## Version details

<Frame>
  ![Version Details panel for a draft version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/version_details_draft.png)
</Frame>

* **State**: Displays the current state of the version (e.g., `draft`, `committed`).
* **Branch**: Indicates the currently selected branch (e.g., `main`).
* **Last Saved By**: Shows the username of the person who last saved changes (e.g., "JS").
* **Last Saved At**: Displays the timestamp of the most recent save (e.g., "23 Jan 2025 at 10:11 AM").
* **ID**: A unique identifier for the version, with a copy button for convenience.
* **Resources Changed**: Displays a summary of modified, added, or deleted resources compared with the previous version (visible only for draft versions with changes).

### Resources changed

The **Resources Changed** section provides a clear overview of all modifications made in the current draft version compared to the last committed version. This helps you track exactly what has been modified before committing your changes.

<Frame>
  ![Resources Changed](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/version_details_resources_changed.png)
</Frame>

The list groups changes by resource type, including:

* **CMS \ Enumerations**: Modified enumeration values (for example, country lists, dropdown options)
* **Processes**: Changed process definitions
* **Project Data Model**: Updates to the data model structure
* **CMS \ Substitution Tags**: Modified substitution tags
* **CMS \ Media Library**: Added, modified, or deleted media assets
* **Task Manager \ Views**: Changes to task manager view configurations
* **Dependencies**: Updated project dependencies
* **Resource Overrides**: Modified resource override configurations

Each resource is color-coded to indicate the type of change:

| Color                   | Meaning           |
| ----------------------- | ----------------- |
| <span>**Yellow**</span> | Modified resource |
| <span>**Green**</span>  | Added resource    |
| <span>**Red**</span>    | Deleted resource  |

<Tip>
  Use the Resources Changed list to review all pending modifications before committing. This ensures you have a complete understanding of what will be included in the commit.
</Tip>

### Compare versions

The **Compare Versions** feature allows you to select two versions and view the differences between them. This is useful for understanding what changes were made between any two points in your project's history.

To compare versions:

1. Select a version in the branch graph
2. Click on the **Compare with current version** button at the bottom of the graph to quickly compare any committed version with the current draft version.

<Frame>
  ![Compare Versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/compare_v.png)
</Frame>

The comparison view displays:

* **Comparing current version**: Shows the first selected version with its branch, state, and last edited timestamp
* **with**: Shows the second selected version being compared against
* **Resources changed**: Lists all resources that differ between the two versions

#### Viewing detailed resource changes

To inspect the specific changes made to a resource, hover over any item in the **Resources changed** list and click the **eye icon** that appears. This opens a detailed comparison modal.

<Frame>
  ![View Resource Changes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-11-27%20at%2017.49.50.png)
</Frame>

The **Changes** modal provides a side-by-side JSON comparison:

* **Left panel**: Shows the version you are comparing with (the previous/committed version)
* **Right panel**: Shows the current draft version
* **Highlighted lines**: Added or modified content is highlighted in green, making it easy to identify what changed

<Frame>
  ![Resource Changes Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-11-27%20at%2017.50.19.png)
</Frame>

<Info>
  This feature helps you track changes across multiple commits, review what was modified before a specific release, or understand the evolution of your project over time.
</Info>

### Resource history

The **Resource History** feature lets you view the version history for a specific resource, showing which project versions included changes to that resource.

To access it, right-click any resource (process, enumeration, substitution tag, media asset, integration, etc.) and select **View History**. This opens the Resource History modal.

The modal displays a table with the following columns:

| Column             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| **Version**        | The project version that included a change to this resource |
| **Last edited by** | The user who last modified the resource in that version     |
| **Last edited at** | The timestamp of the last modification                      |

For each version in the list, you can:

* **See changes** — Opens a comparison view showing what changed in this resource between the selected version and the previous one
* **Open version in new tab** — Navigates to the full project version in a new browser tab

<Info>
  Resource history tracks changes at the project version level. Individual resources do not have their own independent version history — they are always versioned as part of the project.
</Info>

### Branch and commit graph

The graph visually organizes the project’s versioning structure, showing relationships between branches and commits.

* **Graph View**:
  * Provides a visual representation of branches and commits.
  * **Main Branch** (blue): The main development branch.
  * **Secondary Branches** (yellow): Feature or development branches such as `branch3`, `branch4`, and `secondary_branch`.
  * **Markers**:
    * **Dotted Circles**: Represent draft versions.
    * **Solid Circles**: Represent committed versions.

### Commit history

* Displays a chronological list of commit messages for the selected branch.
* **Details**:
  * Commit messages (e.g., `v1`, `commit_secondary_branch`) are aligned with their respective branches.
  * Each commit shows:
    * The user responsible (e.g., "JS").
    * The state of the commit (e.g., `draft`, `commited`).

### Top bar: global controls

* **Project Name**: Displays the current project name (`Docs_customer_onboarding`).
* **Branch Selector**: Dropdown to navigate between branches.
* **State Indicator**: Highlights the state of the current branch (e.g., `draft` for `main`).
* **Commit Changes to Version**: Button for committing draft changes globally.
* **Config/Runtime Tabs**:
  * **Config**: For managing version configuration.
  * **Runtime**: For runtime options or monitoring.

***

## Core versioning operations

The table below summarizes key versioning operations and their functions:

| Operation           | Description                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- |
| **Create Project**  | Creates a project and its initial draft version.                                         |
| **Create Resource** | Adds a new resource in draft status to the current project version.                      |
| **Edit Resource**   | Creates a deep copy of a resource for editing if the original is COMMITTED.              |
| **Commit Project**  | Updates the statuses of the project, its manifest, and resources to COMMITTED.           |
| **Discard draft**   | Deletes draft resources and the draft project version.                                   |
| **Start New draft** | Creates a new draft version by copying the last COMMITTED project version.               |
| **Create Branch**   | Creates a new branch and a corresponding draft project version from the selected commit. |

### Detailed steps for operations

<Steps>
  <Step title="Create Project">
    * A new project is created in draft (WIP) state.
    * An initial draft project version is automatically generated.
  </Step>

  <Step title="Create Resource">
    * Adds a resource in draft status to the current project version.
    * Updates the project manifest to include:
      * **UUID** of the new resource.
      * `last_change_time`: Set to the current timestamp.
      * `last_committed_time`: Null (since the resource is WIP).
  </Step>

  <Step title="Edit Resource">
    * **Scenario A**: Editing a draft Resource
      * No new resource version is created.
      * Updates the project manifest:
        * `last_change_time`: Current timestamp.

    * **Scenario B**: Editing a `COMMITTED` Resource
      * A deep copy of the `COMMITTED` resource is created as draft.
      * Updates the project manifest:
        * Links to the new draft resource.
        * `last_change_time`: Current timestamp.
  </Step>

  <Step title="Commit Project">
    * Commits the current draft project version:
      1. **draft Resources**:
         * Status: Updated to `COMMITTED`.
         * `last_change_time` and `last_committed_time`: Set to the current timestamp.
      2. **Project Version**:
         * Status: Updated to `COMMITTED`.
  </Step>

  <Step title="Discard Draft">
    * Deletes draft resources and the draft project version.
    * Available only when there are changes after the last commit.
  </Step>

  <Step title="Start New Draft">
    * Creates a new draft project version by copying:
      * The last `COMMITTED` project version.
      * Its manifest, linking to `COMMITTED` resources.
  </Step>

  <Step title="Create Branch">
    * Creates a new branch and draft project version:
      * Copies the selected `COMMITTED` project version.
      * Updates the manifest to reference existing `COMMITTED` resources.
  </Step>
</Steps>

***

## Lifecycle of a project version

1. **Create Project**: Automatically starts with a draft (work-in-progress) project version.
2. **Modify Resources**: Draft (WIP) resources can be edited directly, while `COMMITTED` resources are cloned into draft (WIP) before editing.
3. **Commit Changes**: Promotes the project version and its resources to `COMMITTED` status.
4. **Start New WIP**: Allows iterative development by creating a new draft version.
5. **Create Branch**: Enables parallel development with isolated draft versions.

***

## Starting a new draft version

You can initiate a new draft (work-in-progress) version while keeping the committed version intact. A draft version is automatically created under the following circumstances:

* **New Project**: When you create a new project, a corresponding draft version is initiated. This ensures that ongoing changes are tracked separately from the committed version.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2013.35.54.gif)
</Frame>

* **New Branch Creation**: The creation of a new branch in the system also triggers the creation of a draft version (from a committed version only). This simplifies the process of branching and development, allowing for parallel progress without impacting the main committed version.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-28%20at%2013.39.50.png)
</Frame>

* **Manual Draft Version Creation**: You have the flexibility to initiate a new draft version manually. This is particularly useful when building upon the latest version available on a branch.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2013.47.04.gif)
</Frame>

***

## Advanced features

### Committing changes

You can commit changes exclusively on work-in-progress (WIP) versions. Changes can be committed using the designated action within the version menu. Upon triggering the commit action, a modal window appears, prompting you to provide a commit message.

<Info>
  A string of maximum 50 characters, mandatory for commit. Only letters, numbers, and characters \[] () . \_ - / are allowed.
</Info>

The placeholder indicating work-in-progress is replaced with a "committed" state within the graph view.

#### Updating commit messages

You have the flexibility to modify commit messages after changes are committed. This can be accomplished using the action available in the version menu.

### Creating a new branch

Using versioning you can work on a stable copy of the project, isolated from ongoing updates by other users. You can create a new branch starting from a specific commit point.
The initiation of new branches is achieved using the dedicated action located in the left menu of the chosen commit point (used as the starting point for the branch).

<Warning>
  A string of maximum 16 characters, mandatory for branch creation.
</Warning>

### Merging changes

You can incorporate updates made on a secondary branch into the main branch or another secondary branch. To ensure successful merging of changes, adhere to the following criteria:

* You can merge the latest version from a secondary branch into either its direct or indirect parent branch.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2015.42.30.gif)
</Frame>

* Upon triggering the merge action, a modal window appears, giving the possibility to make the following selection:
  * **Branch**: Displays the branches to which the current branch is a child (direct or indirect).
  * **Message**: A string of maximum 50 characters (limited to letters), numbers and the following characters: \[] () . \_ - /.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/merge_changes.png)
</Frame>

The graph representation is updated to display the new version on the selected parent branch and the merged version is automatically selected, facilitating further development and tracking.

### Managing conflicts

The Conflict Resolution and Version Comparison feature provides a mechanism to identify and address conflicts between two process versions that, if merged, could potentially disrupt the integrity of a project.

The system displays both the version to be merged and the current version on a single screen, providing a clear visual representation of the differences. Conflicts and variations between the two versions are highlighted, enabling users to readily identify areas requiring attention.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2015.54.48.gif)
</Frame>

<Tip>
  Unless specified otherwise, changes from the source branch will be prioritized.
</Tip>

<Info>
  Not all changes are considered conflicts, changes in node positions are not treated as conflicts. Primary causes lie in identifying differences within business rules, expressions, and other scripts.
</Info>

#### Merging without conflicts

Easily merge secondary branches into the main branch or other branches when no conflicts are detected. The updated merge modal includes:

* A clean interface for branch selection.
* A mandatory, validated commit message field (max 50 characters).
* Real-time feedback for successful merges and updates to the branching graph.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)
</Frame>

#### Advanced conflict detection

The new **Conflicts Detected Modal** provides a detailed overview of conflicting changes, with features such as:

* Clear grouping by resource type (e.g., Processes, Enumerations, Media Library).
* Scrollable lists and clickable entries to resolve conflicts efficiently.
* A comprehensive comparison of source and target branch differences for context.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)
</Frame>

#### Resource-level conflict resolution

Resolve conflicts directly at the resource level with an intuitive interface:

* **JSON Comparisons:** Visualize differences with color-coded highlights (source: yellow, target: blue).
* **Navigation Support:** Quickly jump between differences for efficient resolution.
* **Progress Tracking:** Mark resources as “Reviewed” or “Seen” to monitor resolution progress.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)
</Frame>

#### Flexible merge overrides

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)
</Frame>

### Read-only state

The Read-Only State feature allows you to access and view committed versions of your projects while safeguarding the configuration from unintended modifications. By recognizing the visual indicators of the read-only state, you can confidently work within a controlled environment, ensuring the integrity of project's process definitions.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-28%20at%2011.54.39.png)
</Frame>

***

## Builds

A **build** is a deployable snapshot of a committed project version, packaged and prepared for deployment to a runtime environment. Builds enable you to create immutable, versioned packages that can be deployed consistently across different environments.

<Info>
  You can create multiple versions of a project before creating a build. You can create a build for any committed project version. Once created, a build cannot be edited—you'll need to create a new project version and generate a new build to incorporate changes.
</Info>

### Creating a build

To create a build from a committed project version:

<Steps>
  <Step title="Navigate to Version Details">
    Access the version details panel for the committed version you want to build. You can only create builds from committed versions, not from draft (WIP) versions.
  </Step>

  <Step title="Open Create Build Dialog">
    Click the **Create Build...** button in the version details panel. This opens the build creation modal.

    <Frame>
      ![Create Build](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build.png)
    </Frame>
  </Step>

  <Step title="Configure Build Settings">
    In the **Create build** modal, configure the following settings:

    * **Name**: The build name (defaults to the project name). This helps identify the build in the builds list.
    * **Build Tag Version**: Set the semantic version for this build:
      * **Major**: Major version number (e.g., `1`)
      * **Minor**: Minor version number (e.g., `0`)
      * **Patch**: Patch version number (e.g., `0`)

    The build tag follows semantic versioning format (e.g., `1.0.0`) and helps track different builds of the same project version.
  </Step>

  <Step title="Save the Build">
    Click **Save** to create the build. The build is now available in the Builds section and can be deployed to runtime environments.
  </Step>
</Steps>

<Frame>
  ![Create Build Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build_modal.png)
</Frame>

### Managing builds

The **Builds** section provides a centralized interface for viewing and managing all builds for your project.

<Frame>
  ![Builds Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/builds_interface.png)
</Frame>

#### Builds list

The builds list displays all builds created for the project, showing:

* **Build name and version**: Displays the build name and tag version (e.g., `Update_process_variables 1.0.0`)
* **Build actions**: Each build entry provides quick access to:
  * **Play/Run**:
    * Test build
    * Test endpoint
    * Test workflow
    * Test operation
  * **Export**:
    * Export the build
  * **More options**: Additional actions via the context menu
    * View contents
    * Workflow test instances
    * Audit log
    * Apply indexes

#### Searching builds

Use the **Search by build tag** field to quickly find specific builds by their version tag or name.

### Exporting versions

You can export project versions for backup, migration, or sharing across environments. The export process includes an option to include binary files.

<Steps>
  <Step title="Select Version to Export">
    Navigate to the version details panel and select the version you want to export.
  </Step>

  <Step title="Initiate Export">
    Click the **Export Version** button in the version details panel.
  </Step>

  <Step title="Choose Binary Files Option">
    When exporting, a modal appears asking whether to include binary files:

    * **Include**: Includes binary files (e.g., images, documents) in the export. This may increase the export size and import time.
    * **Don't include**: Exports only the project structure and configurations without binary files.

    <Warning>
      Including binary files may significantly increase the export file size and the time required to import the version in another environment.
    </Warning>
  </Step>

  <Step title="Complete Export">
    Click **Continue** to proceed with the export. The exported file can be imported into other environments or workspaces.
  </Step>
</Steps>

<Frame>
  ![Export Version Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/export_version.png)
</Frame>

<Info>
  For detailed information about importing exported versions and builds, see the [Export/Import documentation](../../flowx-designer/managing-a-project-flow/export-import-a-process-definition).
</Info>

### Build immutability

Once a build is created, it becomes immutable—you cannot modify its contents. This ensures:

* **Consistency**: The same build behaves identically across all environments
* **Traceability**: You can always identify exactly which project version is running
* **Stability**: Prevents accidental changes that could affect production systems

To incorporate changes into a build:

1. Make your changes in the project (creating a new draft version)
2. Commit the changes to create a new project version
3. Create a new build from the updated committed version

<Frame>
  <video />
</Frame>

***

## Audit view

The "Open Audit View" provides you with a detailed audit log of actions related to work-in-progress (WIP) versions of a process. The primary goal is to ensure transparency and accountability for actions taken before the commit or save process.

You can quickly access and review the history of WIP versions, facilitating efficient decision-making and collaboration.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/versioning_audit_log.gif)
</Frame>


# Reference types in resources usage
Source: https://docs.flowx.ai/5.9/docs/projects/reference-types

Understanding how Reference Type values are determined in the Resource Usage Overview and why certain values appear based on the underlying resource model.

## Overview

The **Resource Usage Overview** in FlowX.AI tracks where and how resources (such as enumerations, media files, processes, and workflows) are referenced throughout your projects. A key column in this overview is the **Reference Type**, which indicates the type of element that directly contains the reference to a resource.

<Frame>
  ![Resource Usage Overview showing Reference Type column](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)
</Frame>

### Why reference type matters

Understanding Reference Type helps you:

* **Identify the exact location** of resource references within your project
* **Understand dependency chains** before modifying or deleting resources
* **Navigate directly** to the element containing the reference
* **Plan impact analysis** when updating shared resources

### How FlowX.AI identifies references

FlowX.AI identifies resource references through **sub-resources**—the actual elements that contain references, rather than their parent containers. This distinction is crucial for understanding why certain Reference Type values appear.

For example, when an enumeration is used in a User Task node, the reference is technically stored inside the **UI Template** attached to that User Task—not in the User Task node itself. Therefore, the Reference Type displays **UI Template**, not "User Task".

***

## Reference type values

Reference type values are derived from two sources in the FlowX data model:

1. **Element Types** — The type of element within a service that contains the reference
2. **Element Path Types** — The specific path or context within that element

### Element types

Element types identify the owner service, source resource, and the element containing the reference:

| Element Type         | Owner Service          | Source Resource    | Description                                                         |
| :------------------- | :--------------------- | :----------------- | :------------------------------------------------------------------ |
| `uiTemplate`         | admin                  | process            | UI Templates attached to nodes or defined as Reusable UI components |
| `action`             | admin                  | process            | Node actions (business rules, Kafka sends, subprocess starts, etc.) |
| `dataModel`          | admin                  | process            | Data model attributes and entity definitions                        |
| `view`               | task-management-plugin | view               | Task management views                                               |
| `hook`               | task-management-plugin | hook               | Task management hooks                                               |
| `allocation-setting` | task-management-plugin | allocation-setting | Task allocation rules                                               |
| `endpoint`           | integration-designer   | system             | System endpoints                                                    |
| `workflowNode`       | integration-designer   | workflow           | Workflow nodes within integration workflows                         |

### Element path types

Element path types provide more granular context about where within an element the reference exists.

#### Process node path types

| Element Type        | Element Description     | Path Type (Reference Type) |
| :------------------ | :---------------------- | :------------------------- |
| `action`            | Start subprocess action | `StartSubProcessHandler`   |
| `uiTemplate/action` | User Task node          | `USER_TASK`                |
| `action/node`       | Service Task node       | `TASK`                     |
| `action`            | Call subprocess node    | `SUBPROCESS_RUN`           |
| `node`              | Embed process node      | `SUBPROCESS_EMBED`         |

#### Task management path types

| Element Type | Element Description | Path Type (Reference Type) |
| :----------- | :------------------ | :------------------------- |
| (none)       | Allocation rule     | `allocation-setting`       |
| (none)       | View                | `view`                     |
| (none)       | Hook                | `hook`                     |

#### Integration Designer path types

| Element Type   | Element Description | Path Type (Reference Type) |
| :------------- | :------------------ | :------------------------- |
| (none)         | System              | `system`                   |
| (none)         | Endpoint            | `endpoint`                 |
| `workflowNode` | Workflow node       | `workflowNode`             |

#### Data model path types

When a resource (like an enumeration) is referenced in a data model attribute, the Reference Type shows the attribute's data type:

| Element Type | Element Description     | Path Type (Reference Type) |
| :----------- | :---------------------- | :------------------------- |
| `dataModel`  | Data model entity       | `entity`                   |
| `dataModel`  | String attribute        | `STRING`                   |
| `dataModel`  | Integer attribute       | `INTEGER`                  |
| `dataModel`  | Float attribute         | `FLOAT`                    |
| `dataModel`  | DateTime attribute      | `DATE_TIME`                |
| `dataModel`  | ZonedDateTime attribute | `ZONE_DATE_TIME`           |
| `dataModel`  | Boolean attribute       | `BOOLEAN`                  |
| `dataModel`  | Object attribute        | `OBJECT`                   |
| `dataModel`  | Enum attribute          | `ENUM`                     |
| `dataModel`  | Currency attribute      | `CURRENCY`                 |

#### UI Template element path types

When a resource is referenced inside a UI Template, the Reference Type shows the specific UI element type:

| Element Type | Element Description  | Path Type (Reference Type) |
| :----------- | :------------------- | :------------------------- |
| `uiTemplate` | Page component       | `PAGE`                     |
| `uiTemplate` | Container component  | `CONTAINER`                |
| `uiTemplate` | Card component       | `CARD`                     |
| `uiTemplate` | Form component       | `FORM`                     |
| `uiTemplate` | Modal component      | `MODAL`                    |
| `uiTemplate` | Stepper component    | `STEPPER`                  |
| `uiTemplate` | Step component       | `STEP`                     |
| `uiTemplate` | Tab component        | `TAB`                      |
| `uiTemplate` | Zone component       | `ZONE`                     |
| `uiTemplate` | Collection component | `COLLECTION`               |
| `uiTemplate` | Table component      | `TABLE`                    |
| `uiTemplate` | Input field          | `INPUT`                    |
| `uiTemplate` | Text area            | `TEXTAREA`                 |
| `uiTemplate` | Select dropdown      | `SELECT`                   |
| `uiTemplate` | Checkbox             | `CHECKBOX`                 |
| `uiTemplate` | Radio button         | `RADIO`                    |
| `uiTemplate` | Switch toggle        | `SWITCH`                   |
| `uiTemplate` | Slider               | `SLIDER`                   |
| `uiTemplate` | Datepicker           | `DATEPICKER`               |
| `uiTemplate` | Button               | `BUTTON`                   |
| `uiTemplate` | Link                 | `LINK`                     |
| `uiTemplate` | Text element         | `TEXT`                     |
| `uiTemplate` | Image element        | `IMAGE`                    |
| `uiTemplate` | Message element      | `MESSAGE`                  |

***

## Why UI element types appear as Reference Types

One of the most common questions about the Resource Usage Overview is:

> "Why does the Reference Type show 'SELECT' or 'IMAGE' instead of 'User Task' when using resources in a User Task?"

### The technical explanation

In FlowX.AI's architecture, **UI Templates contain UI elements** that hold references to resources like enumerations, media files, and substitution tags. The Reference Type shows the **specific UI element type** that contains the reference, not the parent node:

```mermaid theme={"system"}
flowchart TB
    subgraph UserTask["User Task Node"]
        subgraph UITemplate["UI Template"]
            Select["Select Component<br/>(type: SELECT)"]
        end
    end
    
    Enum[("Countries" Enumeration)]
    
    Select -. "Data Source" .-> Enum
    
    Select -.-> RefType["Reference Type = SELECT"]
    
    style RefType fill:#ffd700,stroke:#333,stroke-width:2px
    style Select fill:#e1f5fe,stroke:#0288d1
    style Enum fill:#f3e5f5,stroke:#7b1fa2
```

### The rule

<Warning>
  **Reference Type always reflects the specific element holding the reference, not the process node containing it.**
</Warning>

This means:

| Scenario                       | What contains the reference     | Reference type shown                         |
| :----------------------------- | :------------------------------ | :------------------------------------------- |
| Enumeration in Select dropdown | Select component in UI Template | `SELECT`                                     |
| Enumeration in Radio buttons   | Radio component in UI Template  | `RADIO`                                      |
| Enumeration in Data Model      | Data model attribute            | `ENUM`                                       |
| Media file in Image component  | Image element in UI Template    | `IMAGE`                                      |
| Substitution tag in Text       | Text element in UI Template     | `TEXT`                                       |
| Process called from action     | Action on the node              | `StartSubProcessHandler` or `SUBPROCESS_RUN` |
| Workflow in integration node   | Workflow node                   | `workflowNode`                               |

### Why this design?

This design reflects the actual data model and provides:

1. **Precision** — Shows the exact UI element type or data model attribute type that contains the reference
2. **Consistency** — The same UI element type (like `SELECT`) produces the same Reference Type regardless of whether it's in a User Task or Reusable UI
3. **Actionable information** — You know immediately what type of component needs to be modified if you want to change the reference

***

## Reference type by resource category

Different resource types generate different Reference Type values based on how they're used in the platform.

### Process references

Processes can be referenced from multiple contexts:

| Reference Context                        | Element            | Reference Type           |
| :--------------------------------------- | :----------------- | :----------------------- |
| Start subprocess action                  | Action             | `StartSubProcessHandler` |
| Call activity node                       | Action             | `SUBPROCESS_RUN`         |
| Embedded subprocess                      | Node               | `SUBPROCESS_EMBED`       |
| Task management view                     | View               | `view`                   |
| Task management hook (parent process)    | Hook               | `hook`                   |
| Task management hook (triggered process) | Hook               | `hook`                   |
| Allocation rule                          | Allocation Setting | `allocation-setting`     |

<Info>
  Hooks reference two processes: the **parent process** (which triggers the hook) and the **triggered process** (which runs when the hook fires). Both create separate resource usage entries with Reference Type `hook`.
</Info>

### Enumeration references

Enumerations are primarily referenced in UI components, data models, and integration systems:

| Reference Context                     | Element     | Reference Type |
| :------------------------------------ | :---------- | :------------- |
| Select dropdown                       | UI Template | `SELECT`       |
| Radio button group                    | UI Template | `RADIO`        |
| Checkbox group                        | UI Template | `CHECKBOX`     |
| Data model attribute (ENUM type)      | Data Model  | `ENUM`         |
| System endpoint (enumeration mapping) | Endpoint    | `endpoint`     |

<Tip>
  Enumerations used as data sources in UI components will show the specific UI element type (like `SELECT` or `RADIO`) as the Reference Type, not just "UI Template."
</Tip>

### Media file references

Media files (images, icons, documents) are referenced in UI Templates:

| Reference Context                  | Element     | Reference Type             |
| :--------------------------------- | :---------- | :------------------------- |
| Image component                    | UI Template | `IMAGE`                    |
| Button with icon                   | UI Template | `BUTTON`                   |
| Card component                     | UI Template | `CARD`                     |
| Container background               | UI Template | `CONTAINER`                |
| Any UI element with image property | UI Template | Corresponding element type |

### Substitution tag references

Substitution tags are used for dynamic text content and are only referenced in UI Templates:

| Reference Context           | Element     | Reference Type             |
| :-------------------------- | :---------- | :------------------------- |
| Text element                | UI Template | `TEXT`                     |
| Button label                | UI Template | `BUTTON`                   |
| Input placeholder           | UI Template | `INPUT`                    |
| Any text-containing element | UI Template | Corresponding element type |

<Info>
  Substitution tags are referenced using the format `@@path.to.SubstitutionTag` within UI Template text properties. The Reference Type will show the specific UI element type where the tag is used.
</Info>

### Workflow references

Integration workflows can be referenced from:

| Reference Context                    | Element       | Reference Type |
| :----------------------------------- | :------------ | :------------- |
| Start Integration Workflow action    | Action        | Action type    |
| Receive Message Task (From Workflow) | Node          | Node type      |
| Subworkflow node in another workflow | Workflow Node | `workflowNode` |

### System and endpoint references

Integration systems and their endpoints appear in workflow configurations:

| Reference Context                 | Element       | Reference Type |
| :-------------------------------- | :------------ | :------------- |
| Workflow node using endpoint      | Workflow Node | `workflowNode` |
| Enumeration mapping configuration | Endpoint      | `endpoint`     |

### Resources not tracked as usages

Some resource types are **not used by other resources** and therefore don't appear as Reference Types when viewing other resources:

| Resource Type            | Notes                                                                                 |
| :----------------------- | :------------------------------------------------------------------------------------ |
| View                     | Views use processes, but views themselves are not referenced by other resources       |
| Hook                     | Hooks reference processes, but hooks themselves are not referenced by other resources |
| Allocation Rule          | Allocation rules reference processes, but are not referenced by other resources       |
| Configuration Parameters | Not tracked as resources; used as string values in business rules                     |
| Document Templates       | Referenced by name in Kafka send actions, not by resource ID                          |
| Notification Templates   | Referenced by name in Kafka send actions, not by resource ID                          |

***

## Examples

### Example 1: enumeration used inside a User Task

**Scenario**: You have a "Country" enumeration used in a Select dropdown within a User Task node's UI.

**Resource**: `Countries` enumeration\
**Location**: User Task node → UI Template → Select component → Data Source

**Result in Usage Overview**:

| Resource  | Reference Type | Reference Path                                          |
| :-------- | :------------- | :------------------------------------------------------ |
| Countries | `SELECT`       | Process: Onboarding → Node: SelectCountry → UI Template |

<Tip>
  Even though you navigate through the User Task to find this enumeration, the **Reference Type is `SELECT`** because that's the specific UI element type that contains the data source reference.
</Tip>

### Example 2: enumeration used inside a Reusable UI

**Scenario**: You have a "Document Types" enumeration used in a Select component within a Reusable UI component.

**Resource**: `DocumentTypes` enumeration\
**Location**: Reusable UI → UI Template → Select component → Data Source

**Result in Usage Overview**:

| Resource      | Reference Type | Reference Path                              |
| :------------ | :------------- | :------------------------------------------ |
| DocumentTypes | `SELECT`       | Reusable UI: DocumentSelector → UI Template |

<Info>
  Notice that both User Task UI and Reusable UI show **`SELECT`** as the Reference Type. This is because the referencing element is a Select component in both cases, regardless of whether it's in a User Task or Reusable UI.
</Info>

### Example 3: workflow referenced in a workflow node

**Scenario**: An integration workflow "SendNotification" calls another workflow "EmailService" from one of its nodes.

**Resource**: `EmailService` workflow\
**Location**: Workflow: SendNotification → Workflow Node: CallEmail

**Result in Usage Overview**:

| Resource     | Reference Type | Reference Path                               |
| :----------- | :------------- | :------------------------------------------- |
| EmailService | workflowNode   | Workflow: SendNotification → Node: CallEmail |

### Example 4: data model attribute using ENUM type

**Scenario**: A data model has an attribute "accountType" with type ENUM referencing the "AccountTypes" enumeration.

**Resource**: `AccountTypes` enumeration\
**Location**: Process: AccountOpening → Data Model → accountType attribute

**Result in Usage Overview**:

| Resource     | Reference Type | Reference Path                                    |
| :----------- | :------------- | :------------------------------------------------ |
| AccountTypes | ENUM           | Process: AccountOpening → Data Model: accountType |

### Example 5: media file used in UI Template inside a node

**Scenario**: A company logo image is used in a Card component header within a User Task.

**Resource**: `company_logo.png` media file\
**Location**: User Task node → UI Template → Card → Image component

**Result in Usage Overview**:

| Resource          | Reference Type | Reference Path                                      |
| :---------------- | :------------- | :-------------------------------------------------- |
| company\_logo.png | `IMAGE`        | Process: Welcome → Node: ShowBranding → UI Template |

<Warning>
  The Reference Type is **`IMAGE`** (the UI element type), not "User Task" or the specific node type. The media file reference lives inside an Image component within the UI Template, regardless of which node contains that template.
</Warning>

***

## How resource usage tracking works

Understanding the technical architecture behind resource usage tracking helps explain why Reference Types appear the way they do.

### Resource usage data model

When a resource reference is detected, FlowX.AI stores the following information:

| Field                         | Description                                                |
| :---------------------------- | :--------------------------------------------------------- |
| Source Application Version    | The app version containing the reference                   |
| Source Resource Definition ID | The resource definition where the reference exists         |
| Source Resource Type          | Type of the containing resource (such as process)          |
| Source Element ID             | The specific sub-element ID (such as UI Template ID)       |
| Source Element Type           | The type of sub-element (such as `uiTemplate` or `action`) |
| Source Location               | The specific field path (such as `flowxProps.dataSource`)  |
| Target Resource Definition ID | The referenced resource's definition ID                    |
| Target Application ID         | The app containing the referenced resource                 |
| Target Resource Type          | Type of the referenced resource (such as enumeration)      |

### Operations that affect resource usages

Resource usage entries are created, updated, or deleted when you perform these operations:

**For UI Templates:**

* Update UI template properties
* Delete UI template
* Copy/paste UI templates or nodes
* Undo/redo operations
* Import/export processes

**For Actions:**

* Create, update, or delete actions
* Update node configurations
* Copy/paste nodes
* Import/export processes

**For Data Model:**

* Add or modify attributes with ENUM type
* Delete data model attributes

**For Task Management:**

* Create, update, or delete views
* Create, update, or delete hooks
* Create or delete allocation rules

**For Integration Designer:**

* Configure workflow nodes
* Set up endpoint enumeration mappings

***

## Understanding the resource hierarchy

To fully understand Reference Types, it helps to understand FlowX.AI's resource hierarchy:

### Resources vs sub-resources

| Category                                 | Examples                                                     | Can be a Reference Type?                                      |
| :--------------------------------------- | :----------------------------------------------------------- | :------------------------------------------------------------ |
| **Top-level resources**                  | Processes, Workflows, Enumerations, Media Files, Systems     | These are what get referenced, not reference types themselves |
| **Sub-resources (reference containers)** | UI Templates, Actions, Data Model attributes, Workflow Nodes | Yes, these appear as reference types                          |
| **Parent containers**                    | User Task nodes, Service Task nodes, Gateway nodes           | No, the parent node type is not the reference type            |

### Why parent node types never appear as reference types

Parent nodes (like User Task, Service Task, or Call Activity) are containers that **hold** sub-resources. The actual reference always lives inside a sub-resource:

* **User Task** → contains UI Template (reference is in UI Template)
* **Service Task** → contains Actions (reference is in Action)
* **Call Activity** → contains Action configuration (reference is in Action)

The parent node type provides **context** for navigation but is not the Reference Type itself.

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why doesn't Reference Type show 'User Task'?">
    Reference Type reflects the **actual element containing the reference**, not the parent node. When you use an enumeration in a User Task's interface, the reference is stored in the **UI Template** attached to that User Task. Therefore, the Reference Type shows the specific UI element type (like `SELECT` or `RADIO`).

    The User Task is simply the container node—it doesn't directly hold the enumeration reference; the UI Template inside it does.
  </Accordion>

  <Accordion title="Why does everything look like a UI element type?">
    Many resources (enumerations, media files, substitution tags) are primarily used within user interfaces. Since all UI components are defined inside UI Templates—whether those templates are attached to User Tasks, Reusable UI components, or other UI-enabled nodes—the Reference Type shows the specific UI element type (like `SELECT`, `IMAGE`, `TEXT`, etc.).

    This is accurate and provides precise information about exactly which UI component contains the reference.
  </Accordion>

  <Accordion title="Can navigation areas create resource usages?">
    Navigation areas define the structure and routing of your application's UI. If a navigation area has an associated UI Template that references resources like enumerations or media files, those references will be tracked with the corresponding UI element type as the Reference Type.
  </Accordion>

  <Accordion title="Do configuration parameters appear as Reference Types?">
    No. Configuration parameters are not tracked as resources. They are used as string values within business rules and do not appear in the Resource Usage Overview. The usage of configuration parameters is not set explicitly—they are configured in business rules as strings.
  </Accordion>

  <Accordion title="Do substitution tag values appear as Reference Types?">
    Substitution tags are referenced in UI Templates using the format `@@path.to.SubstitutionTag`. When you view the usage of a substitution tag, the Reference Type will show the specific UI element type (like `TEXT` or `BUTTON`) where the tag is embedded.

    Note that substitution tags exist as a single resource per application version, and only their individual values are tracked for usage.
  </Accordion>

  <Accordion title="How do I find all usages of a resource in User Tasks specifically?">
    While the Reference Type shows the specific UI element type, the **Reference Path** column provides the full context including the parent node. You can use this path to identify which User Tasks contain UI elements that reference your resource.

    Look for paths like: `Process: [Name] → Node: [UserTaskName] → UI Template`
  </Accordion>

  <Accordion title="What's the difference between 'action' and specific handler types like 'StartSubProcessHandler'?">
    The Reference Type can show either the general element type (`action`) or a more specific path type depending on the context:

    * **`StartSubProcessHandler`** — Start subprocess action type
    * **`SUBPROCESS_RUN`** — Call activity (call subprocess) node
    * **`SUBPROCESS_EMBED`** — Embedded subprocess node
    * **`TASK`** — Service task node
    * **`USER_TASK`** — User task node

    The specific types provide more granular information about what kind of node or action holds the reference.
  </Accordion>

  <Accordion title="Why don't Document and Notification Templates appear in resource usages?">
    Document templates and notification templates are referenced **by name** in Kafka send action configurations, not by resource ID. The actual template resource ID is resolved at runtime by the document and notification services based on the template name and build ID. Because they're referenced by name (a string value) rather than by resource definition ID, they are not tracked in the Resource Usage Overview.
  </Accordion>

  <Accordion title="What happens to resource usages when I create a new application version?">
    When you create a new application version (WIP), the resource usages are cloned from the source version. This ensures that the new version has an accurate picture of all resource references. When you discard a WIP version, its resource usages are also discarded.
  </Accordion>

  <Accordion title="What happens to resource usages during import/export?">
    Resource usages are included when exporting applications and are restored during import. The resource definition IDs remain the same when exporting and importing an application, ensuring that the usage tracking remains accurate.
  </Accordion>

  <Accordion title="Can I see usages for resources from library dependencies?">
    Yes. When your project uses resources from library dependencies (like enumerations or media files from a shared library), those usages are tracked. The resource usage entry stores both the source location (where the reference exists in your project) and the target resource information (including the library's application ID).
  </Accordion>
</AccordionGroup>

***

## Summary

The Reference Type in the Resource Usage Overview accurately reflects FlowX.AI's internal resource model:

<Steps>
  <Step title="References live in sub-resources">
    Actual resource references are stored in sub-resources like UI Templates, Actions, and Data Model attributes—not in parent node types.
  </Step>

  <Step title="Reference Type shows the container">
    The Reference Type displays the type of element that directly contains the reference, providing accurate technical information.
  </Step>

  <Step title="Parent context is in the path">
    While the Reference Type shows "UI Template", the full Reference Path includes parent information like the node name and process for complete context.
  </Step>

  <Step title="Consistency across contexts">
    The same resource used in different contexts (User Task UI vs. Reusable UI) shows the same Reference Type because the referencing element is the same—a UI Template.
  </Step>
</Steps>

Understanding this model helps you:

* Correctly interpret the Resource Usage Overview
* Plan changes with accurate impact analysis
* Navigate efficiently to the actual location of resource references


# Resources
Source: https://docs.flowx.ai/5.9/docs/projects/resources

Overview of Global and project resources, including their usage, dependencies, promotion, and configuration within the platform.

## Overview

Resources are categorized into **Global Resources** and **Project Resources**. Each type has unique characteristics that define its usage, dependencies, and promotion between environments. Understanding these distinctions ensures efficient project development, management, and deployment.

***

## Global resources

Global Resources are designed for **reuse across multiple projects** or business contexts.

<Info>
  These resources are often organized within **libraries**, enabling consistency and efficiency by providing a central repository of shared components.
</Info>

### Key characteristics

* **Reusable**: Common design elements, themes, fonts, and other assets can be used in multiple projects.
* **Independent**: Global Resources exist outside individual projects, making them adaptable across different business cases.
* **No Dependencies**: These resources are not project-specific, making them versatile for broad use cases. Projects can reference libraries without requiring modifications to the core resources.

### Examples

#### Design assets

* **Themes**: Standardized themes for consistent styling.
* **Global Media Library**: Shared images, icons, and other assets.
* **Fonts**: Reusable font families to maintain branding.

#### Plugins

* **Languages**: Language packs or configurations that support multilingual capabilities across projects.
* **Templates**: Notification and document templates managed at a global level.
* **Out-of-Office Settings**: Platform-wide absence management settings.

#### General settings

* **Users**: User accounts and profiles that can be accessed across multiple projects.
* **Roles**: Defined roles that determine user permissions and access levels.
* **Groups**: User groupings that facilitate collective management and permissions.
* **Audit Log**: Logs that track changes and activities within the platform for security and compliance purposes.

#### Libraries

Organized resource containers including **enumerations**, **substitution tags**, and **CMS components** for multi-project use.

### Promotion workflow

* **Library Promotion**: Global Resources within libraries are promoted separately from projects. They are typically **imported into the Designer UI** in target environments as part of their own libraries.
* **Configuration Management**: When libraries are promoted, existing configurations, such as **generic parameters**, are replaced by project-level configurations in the target environment.

***

## Project resources

Project Resources are specific to a **business use case**. Unlike Global Resources, they belong to a single project, allowing for custom configurations and dependencies on libraries.

### Key characteristics

* **Project-Specific**: Tailored to a single project’s needs.
* **Library Dependencies**: Can reference and extend Global Resources.
* **Configurable**: Parameters can be updated in upper environments through environment variables or overrides.

### Examples

1. **Processes**: BPMN workflows customized for the project’s business logic.
2. **CMS Components**: Project-specific enumerations, substitution tags, and media items.
3. **Task Management**:
   * **Views**: Configurable interfaces to display task-related data based on process definitions.
   * **Stages**: Stages that allow task progression through different statuses.
   * **Allocation rules**: Define how tasks are assigned to users or teams.
4. **Integration Designer**:
   * **Systems**: A system is a collection of resources—endpoints, authentication, and variables—used to define and run integration workflows.
   * **Workflows**: A workflow defines a series of tasks and processes to automate system integrations. Within the Integration Designer, workflows can be configured using different components to ensure efficient data exchange and process orchestration.
5. **Configuration Parameters**: Project-specific rendering settings like `applicationUuid`, `locale`, `language`, and `process parameters`.
6. **Project Builds**: Builds represent finalized versions of the project, including all associated metadata and linked library versions.
7. **Project Settings**: Configure various aspects of a project like platform type, default theme, formatting, etc.

### Promotion workflow

* **Build-Based Promotion**: Only **builds** (not commits) are promoted.
* **Design Asset Handling**: Referenced assets are created if missing but are not updated during import.
* **Configuration Parameters Overrides**: Environment variables replace default values in upper environments.

***

## Resources usage tracking

Track where resources are used to prevent unintended changes and ensure stability.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)
</Frame>

The **Resource Usage Tracking** feature provides real-time visibility into where and how resources are being used, preventing unintended changes and ensuring system stability.

**Key features**

* **View Dependencies** before making updates or deletions.
* **Understand Resource Interactions** across projects.
* **Prevent Issues** when modifying critical elements.

Each resource type includes a **Usage Overview modal**, which updates dynamically as references change.

### Process usage

1. **Access Usage Overview**
   * Click the **Usage Overview icon** in the **Process List**.
2. **Usage Modal Details**
   * Displays references by resource type (e.g., Process, UI Template, Workflow).
   * Provides detailed context, including node configurations.

#### Deleting a process with references

* A **confirmation modal** warns users before deletion.
* The modal lists all affected references.

### Enumeration usage

1. **Access Usage Overview**
   * Click the **Usage Overview icon** in the **Enumeration List**.
2. **Usage Modal Details**
   * Shows where the enumeration is referenced (e.g., UI Designer, Data Model, Workflow)

### Media library usage

1. **Access Usage Overview**
   * Click the **Usage Overview icon** in the **Media Library List**.
2. **Usage Modal Details**
   * Displays where media files are used (e.g., UI Template, Process).

***

### Managing dependencies & tracking changes

* **Dynamic Updates**: Reference lists update automatically as resources change.
* **Dependency Checks**: Users see affected resources before deletion.
* **Bidirectional Tracking**: The **Usage Overview modal** also shows resources referenced **inside** a process.

## Copying resources

Use the **Copy to Another Project** feature to transfer resources while maintaining dependencies.

<Frame>
  <video />
</Frame>

<Steps>
  <Step title="Select a resource from the list">
    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.23.08.png)
    </Frame>
  </Step>

  <Step title="Choose a Destination Project or Library">
    Choose the target project or library.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.28.04.png)
    </Frame>
  </Step>

  <Step title="Pick a branch (if applicable)">
    Select the target branch.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.29.50.png)
    </Frame>
  </Step>

  <Step title="Review Dependencies before copying">
    The system displays referenced resources and validates dependencies.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.47.22.png)
    </Frame>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.48.53.png)
    </Frame>
  </Step>

  <Step title="Include Substitution Tags (optional)">
    If necessary, copy all substitution tags from a project to the target project. Existing substitution tags in the target project with the same key will not be overwritten.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.52.45.png)
    </Frame>
  </Step>

  <Step title="Resolve Identifier Conflicts">
    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.54.07.png)
    </Frame>

    If an identifier already exists in the destination, you'll be prompted to either:

    * **Keep Both**: Create a duplicate.
    * **Replace**: Overwrite existing resource.
    * **Use Destination**: Keep existing resource without copying.
  </Step>
</Steps>

<Tip>
  **Handling conflicts:** The system automatically detects duplicate identifiers and provides a clear choice to avoid unintended overwrites.
</Tip>

### Supported resource types

The copy feature is available for the following resources:

* **Process definitions** (including referenced resources)
* **Systems**
* **Workflows**
* **Enumerations** (including child enumerations)
* **Media Library items**
* **Notification** and **Document** templates

## Duplicating resources

The **Duplicate Resource** feature allows users to quickly copy resources within the same project or library.

<Frame>
  <video />
</Frame>

### Supported resource types

* **Processes**
* **Enumerations**
* **Media files (including Global media library files)**
* **Notification templates**
* **Document templates**
* **Views**

### Steps

<Steps>
  <Step title="Open the Three-Dot Menu next to the resources">
    Duplicate options are available from each resource’s three-dot menu (table row & secondary navigation).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2014.13.45.png)
    </Frame>
  </Step>

  <Step title="Select Duplicate">
    When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2014.18.31.png)
    </Frame>
  </Step>
</Steps>

***

## Resources overrides

Resource overrides enable **localization and customization** of core business applications across multiple regions while maintaining centralized updates from headquarters.

<Info>
  Resource overrides are **only available at the project level**. Libraries cannot contain resource overrides.
</Info>

### Why use resource overrides?

Resource overrides are essential for organizations that need to:

* **Build and maintain a business application HQ** that expands to multiple countries
* **Customize the core application** for each country's specific requirements
* **Keep receiving updates from HQ** without losing local customizations

<Tip>
  Think of resource overrides as a way to maintain a "master copy" at headquarters while allowing each region to adapt specific business logic, compliance requirements, or local regulations.
</Tip>

***

## Managing resource overrides

Resource overrides are configured through the **Dependencies** page in your project's main navigation. This interface provides comprehensive management capabilities for all your library resource customizations.

### Accessing resource overrides

<Steps>
  <Step title="Navigate to Dependencies">
    From your project's main menu, click on **Dependencies** to access the configuration interface.
  </Step>

  <Step title="Select Resource Overrides tab">
    The Dependencies page contains two tabs:

    * **Dependencies**: Manages project library dependencies
    * **Resource Overrides**: Configures and manages all resource overrides
  </Step>
</Steps>

### Resource overrides interface

The Resource Overrides tab displays all configured overrides in a comprehensive table with the following columns:

* **Resource Type**: The type of resource being overridden (Process, Workflow, Enumeration)
* **Original Resource**: The name of the library resource being overridden
* **Original Library**: The library containing the original resource
* **Override Resource**: The name of the resource used as the override
* **Override Source**: The source of the override resource (library name or "Local" for project resources)
* **Actions**: Edit and delete options for each override

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
</Frame>

### Adding a new override

<Steps>
  <Step title="Create new override">
    Click the **+** button to add a new editable row at the top of the table.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro2.pngs)
    </Frame>
  </Step>

  <Step title="Select resource type">
    Choose from the available resource types:

    * **Process**
    * **Workflow**
    * **Enumeration**

    <Warning>
      Changing the resource type will clear any selections in the Original Resource and Override Resource fields.
    </Warning>
  </Step>

  <Step title="Choose original resource">
    Select the library resource you want to override:

    * Search through all available resources of the selected type
    * Resources are grouped by their source library
    * Already overridden resources appear disabled with a tooltip: *"An override already exists for \[resource name]"*

    The **Original Library** field automatically populates with the selected resource's library.
  </Step>

  <Step title="Select override resource">
    Choose the resource to use as the override:

    * Available resources include both local project resources and library resources
    * Resources are grouped by source (project or library)
    * Must match the selected resource type

    The **Override Source** field automatically shows "Local" for project resources or the library name for library resources.
  </Step>

  <Step title="Save or cancel">
    * **Save**: Validates required fields and persists the override
    * **Cancel (X)**: Discards the new override without saving

    <Check>
      Success message: "Resource override has been successfully added."
    </Check>
  </Step>
</Steps>

### Updating an existing override

<Steps>
  <Step title="Enter edit mode">
    Click the **Edit** icon on any override row to make it editable.
  </Step>

  <Step title="Modify fields">
    Update any of the override configuration fields following the same validation rules as adding a new override.
  </Step>

  <Step title="Save changes">
    * **Save**: Applies your changes to the override
    * **Cancel (X)**: Reverts to the original configuration

    <Check>
      Success message: "Resource override has been successfully updated."
    </Check>
  </Step>
</Steps>

### Deleting an override

<Warning>
  Deleting an override will revert the project to using the original library resource at runtime.
</Warning>

<Steps>
  <Step title="Initiate deletion">
    Click the **Delete** icon on the override you want to remove.
  </Step>

  <Step title="Confirm deletion">
    A confirmation modal appears asking you to confirm the deletion.
  </Step>

  <Step title="Complete deletion">
    Click **Confirm Delete** to permanently remove the override.

    <Check>
      Success message: "Resource override has been successfully deleted."
    </Check>
  </Step>
</Steps>

### Export and import with overrides

Resource overrides are automatically included when exporting and importing project versions or builds.

#### Export behavior

When exporting a project version or build:

* A JSON file containing all resource overrides is included in the export ZIP
* Override definitions include complete resource mapping information
* Both original and override resource metadata are preserved

#### Import behavior

When importing a project with resource overrides:

* All override configurations are restored from the JSON file
* Dependencies on referenced libraries are validated
* Override mappings are reestablished in the target environment

<Tip>
  Always verify that required library dependencies are available in the target environment before importing projects with resource overrides.
</Tip>

### Enumeration override behavior

Enumerations have special handling due to their usage patterns across the platform:

#### Current enumeration resolution

* Enumerations are resolved **by name** at runtime
* If multiple enumerations exist with the same name in the dependency tree:
  * The closest one to the project root is chosen
  * If multiple exist at the same level, the one from the build with the most recent creation date is selected

#### Enumeration usage contexts

* **UI Components**: Radio buttons, dropdowns, and multi-select components reference enumerations by name
* **Kafka Actions**: Enumeration names are embedded in message request bodies
* **Data Sources**: Enumeration mapping in endpoint configurations for value transformation
* **CMS Translation**: Both Kafka and REST requests use enumeration names for translation services

<Warning>
  **Current limitation**: For enumeration value transformation between different system codes, the enumeration must exist in the same library or project as the system configuration. Resource overrides will not work for cross-library enumeration transformations.
</Warning>

### Error handling and validation

The interface provides comprehensive error handling:

#### Validation errors

* **Required field missing**: *"This field is required"*
* **Duplicate override**: *"An override already exists for \[resource name]"*

#### System errors

* **Save error**: *"An error occurred while saving resource override. Please try again later."*
* **Update error**: *"An error occurred while updating resource override. Please try again later."*
* **Delete error**: *"An error occurred while deleting resource override. Please try again later."*

### Empty state

When no resource overrides are configured, the interface displays an empty state with guidance on how to create your first override.

***

## Technical concepts

Understanding the technical implementation of resource overrides helps ensure successful customization while maintaining system integrity.

### How resource overrides work

Resource overrides replace library resources at runtime while preserving the original library structure and dependencies.

#### Process overrides

When overriding processes from libraries:

* **Input/output mapping**: Ensure processes properly map input and output data
* **Node compatibility**: The override process must maintain compatibility with the original process structure
* **Data model validation**: Overrides are validated against the data model and number of nodes

<Info>
  You cannot completely replace a process with an entirely different process. The override must maintain the core structure and interface of the original process from the library.
</Info>

#### Complex process scenarios

For processes with **multiple start nodes and end nodes**:

* Validation occurs on both data model structure and node count
* Each start/end node must have a corresponding match in the override
* Business logic can be customized while maintaining the process interface

#### Enumeration and workflow overrides

Unlike processes, **enumerations and workflows** offer more flexibility:

* Can override any enumeration with any other enumeration
* Workflow overrides allow complete replacement of business logic
* Useful for country-specific value lists and decision trees

### Override workflow

<Steps>
  <Step title="Identify library dependency">
    Ensure your project has a dependency on the library containing the resource to override.
  </Step>

  <Step title="Select resource for override">
    Navigate to the library resource you want to customize for your project.
  </Step>

  <Step title="Create override">
    Use the override functionality to create a project-specific version while maintaining the library reference.
  </Step>

  <Step title="Customize business logic">
    Modify the override to meet local requirements while preserving input/output compatibility.
  </Step>

  <Step title="Test integration">
    Validate that the override works correctly with call activities and other dependent resources.
  </Step>
</Steps>

### Current limitations

<Warning>
  Be aware of these limitations in the current implementation:
</Warning>

* **Runtime error detection**: Some overrides with errors may only be discovered at runtime rather than design time
* **Merge conflict visibility**: When comparing JSON configurations, you'll see UUIDs instead of human-readable resource names
* **Dynamic list updates**: If library resources change significantly, they may not appear in the available override list
* **Dependency validation**: If a start node is deleted in a newer library version and doesn't match your override dependency, the system will fail at runtime

### Best practices

* **Design with overrides in mind**: When creating library processes, consider which elements might need localization
* **Maintain interface compatibility**: Ensure overrides preserve the original process's input/output contract
* **Test thoroughly**: Validate overrides in a staging environment before production deployment
* **Version management**: Keep track of library versions and test override compatibility with updates
* **Documentation**: Document the specific business reasons for each override to help with maintenance

<Tip>
  Start with a well-designed reference application in your library, then create minimal, targeted overrides rather than extensive modifications. This approach makes it easier to receive and integrate updates from headquarters.
</Tip>

***

## Use cases and examples

Resource overrides are particularly valuable in enterprise scenarios where centralized governance meets local customization needs.

### Multi-country application deployment

Consider a financial services company with headquarters developing a core onboarding application that needs to be deployed across different countries, each with unique requirements:

#### Architecture overview

<Steps>
  <Step title="Master copy in library">
    The **reference application** (master copy) is maintained in a **library** at headquarters, containing:

    * Core business logic
    * Standard processes (e.g., client onboarding, overdraft management)
    * Common UI components and workflows
    * Base data models and enumerations
  </Step>

  <Step title="Country-specific projects">
    Each country has its own **project** with:

    * Dependencies on the master library
    * Country-specific overrides for local requirements
    * Custom business rules and compliance logic
  </Step>

  <Step title="Process execution with call activities">
    Country projects start processes using **call activities** that:

    * Reference the master processes from the library
    * Apply local overrides where needed
    * Handle country-specific data transformations
  </Step>
</Steps>

#### Localization examples

Different countries often require customized logic for:

* **Exchange rates calculation**: Each country may use different formulas or data sources
* **Privacy policy collection**: Some countries have stricter data protection requirements
* **Compliance workflows**: Regulatory requirements vary by jurisdiction
* **Authentication methods**: Local preferences for OTP, biometric verification, etc.

### Common override scenarios

* **Regulatory compliance**: Adapting processes to meet local legal requirements
* **Language localization**: Customizing enumerations and UI elements for different markets
* **Business logic variations**: Implementing region-specific calculation methods or validation rules
* **Integration differences**: Connecting to different local systems or service providers
* **User experience adaptations**: Modifying workflows to match local business practices


# Active policy
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-policy

The Active policy defines the strategy for selecting which build version of a project is active in the runtime environment.

This feature plays a key role in ensuring that the correct [**project**](../managing-applications/application) configuration is executed, managing how processes interact with specific builds, and controlling how changes propagate through environments. The active policy determines which project version is currently "live" and dictates how updates and new builds are adopted.

<Frame>
  ![Active Policy](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap1.png)
</Frame>

<Note>
  Active Policy supports both global policies that apply to all users and specific policy overrides for individual users or groups, allowing independent testing of different builds or branches.
</Note>

<Warning>
  **Role-based overrides are deprecated in 5.9.0.** New overrides target users or groups; the **Role** override type has been removed from the Add / Edit modal. Any role overrides carried over from a 5.1.x upgrade remain visible in the table but are marked **DEPRECATED**, are excluded from runtime resolution, and can only be deleted. Recreate the intended access using a [group override](#policy-overrides) instead. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.
</Warning>

## Key concepts

### Active build

* The active build is the currently selected version of a project that is deployed in the runtime environment. It is the version that all process executions will reference when initiated.
* While a global policy applies to all users by default, individual policy overrides can specify different active builds for specific users or groups.

### Policy types

* **Latest on Branch**: Configures the project to run the latest version on a specific branch. This is useful for environments like development or testing, where ongoing changes need to be reflected in real-time.
* **Build**: Points to a specific build from the available builds for the project. This policy ensures that only the selected build is used, preventing unexpected updates. It is typically used for UAT and Production environments.

### Policy hierarchy

* **Global Policy**: The default policy that applies to all users unless overridden.
* **Policy Overrides**: User-specific or group-specific policies that take precedence over the global policy for targeted users.
* Policy overrides enable independent testing of different builds or branches without affecting other users.

### Version control and flexibility

* Active Policy provides flexibility by allowing different users to work with different build versions simultaneously.
* By managing both global policies and overrides, you control which changes go live for which users and when, allowing for testing and controlled rollouts.

## Global policy

The Global Policy section defines the default active policy that applies to all users unless specifically overridden by individual policy overrides.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap4.png)
</Frame>

<Steps>
  <Step title="Navigate to Active Policy">
    Go to your project's **Runtime Settings** and select the **Active Policy** tab.
  </Step>

  <Step title="Configure Global Policy">
    In the **Global Policy** section, choose your policy type:

    * **Latest on Branch**: Always use the latest version on the selected branch
    * **Build**: Usa specific build from the available builds for the project

    Select the appropriate branch and build version based on your policy choice.
  </Step>

  <Step title="Update Policy">
    Click **Update** to apply the global policy changes.

    <Check>
      The policy takes effect immediately for all users without specific overrides.
    </Check>
  </Step>
</Steps>

## Policy overrides

Policy Overrides allow you to define specific active policies for individual users or groups, enabling independent testing of different builds or branches without affecting the global policy.

<Warning>
  **Known limitation:** Adding a policy override currently requires the **org\_admin** role. Although workspace\_admin and runtime\_editor can open the **Add Policy Override** dialog, selecting a user or group fails with a permissions error. A fix is planned for an upcoming release so these roles can add overrides directly. In the meantime, ask an org\_admin to add the override, or grant the user a role that includes organization-level user and group read.
</Warning>

<Info>
  Define policies for specific users or groups to simulate conditions and test branch behavior independently from the global policy.
</Info>

### Managing policy overrides

The Policy Overrides section provides comprehensive tools for creating, managing, and monitoring user-specific and group-specific active policies.

#### Override table structure

The policy overrides are displayed in a table with the following columns:

* Override Type: Specifies whether the override applies to a **Username** or **Group**.
* Applies To: Indicates the specific Runtime User (by username) or Runtime Group (by group name) that this policy override applies to.
* Policy: Specifies the policy type to use for the override.
* Branch/Build Version: Specifies the branch or build version to use for the override.
* Priority: Required for **Group** overrides; ignored for **Username** overrides. Lower numbers take precedence when multiple group overrides apply to the same user.
* Status: Shows whether the override is **Active** or **Inactive**.

<Note>
  Legacy **Role** overrides created before 5.9.0 still appear in this table with a **DEPRECATED** marker. They are visually muted, can only be deleted (no edit), and are excluded from runtime resolution. Recreate them as group overrides.
</Note>

#### Search and filter

Use the search functionality to quickly locate specific overrides:

* **Search by Username**: Enter a username to filter overrides for specific users
* **Search by Group**: Enter a group name to filter overrides for specific groups
* The search filters the table in real-time as you type

<Steps>
  <Step title="Add New Override">
    Click the **Add** button (+ icon) to create a new policy override.
  </Step>

  <Step title="Configure Override Type">
    Select whether the override applies to a **Username** or **Group**:

    * **Username**: Choose a specific user from the dropdown
    * **Group**: Select a runtime group from the available options. The picker lists only groups that have a runtime role configured for the current project.
  </Step>

  <Step title="Set Policy Configuration">
    Choose the policy type:

    * **Latest on Branch**: Select the branch to use
    * **Build**: Choose a specific build version
  </Step>

  <Step title="Set Priority (Group overrides only)">
    Group overrides require a priority to resolve conflicts when a user belongs to several groups that each have an override.

    <Warning>
      Priority is mandatory for group overrides and must be unique across all group overrides on the same project. Saving a group override without a priority or with a duplicate value is blocked with a validation error.
    </Warning>

    <Tip>
      Lower numbers = higher priority. Use priority 0 for the most critical overrides.
    </Tip>

    Username overrides do not use priority; they always take precedence over any group override.
  </Step>

  <Step title="Enable Override">
    Check **Enable this override** to activate it immediately, or leave unchecked to create it in an inactive state.
  </Step>

  <Step title="Create Override">
    Click **Create Override** to save the new policy override.

    <Check>
      The override appears in the table and takes effect immediately if enabled.
    </Check>
  </Step>
</Steps>

#### Override management actions

Each override in the table provides several management options:

**Edit Override**

* Click the edit icon to modify override settings
* Update policy type, target build/branch, or priority
* Changes take effect immediately upon saving

**Contextual Menu Actions**

* **Activate/Deactivate**: Toggle the override on or off without deleting it
* **Delete**: Permanently remove the override

<Warning>
  Deleting an override immediately reverts affected users to the global policy. Ensure this change is intentional.
</Warning>

## Key features

### Environment-specific control

* Each environment can have its own global policy and set of policy overrides
* Control what version of the project runs for different user groups at each stage of development

### User-specific testing

* Policy overrides enable individual users or groups to test different builds independently
* Developers can work and test their ongoing work simultaneously without conflicts
* QA teams can test specific builds while production users remain on stable versions

### Priority-based resolution

* When multiple group overrides apply to the same user, priority determines which takes precedence
* Fine-grained control over policy application in complex scenarios
* Clear hierarchy: Username overrides > Group overrides (lowest priority number wins) > Global policy

### Rollback capability

* Easily revert to previous builds by updating the global policy or specific overrides
* Quick rollback minimizes disruption and maintains system stability
* Independent rollback for specific users without affecting others

### Branch-specific management

* Support for branch-based policies in both global settings and overrides
* Parallel development with different active branches for different user groups
* Flexible testing scenarios across multiple development streams

## Benefits

* **Controlled Rollouts**: Gradual deployment to specific users or groups before wider release
* **Independent Testing**: Users can test different builds simultaneously without conflicts
* **Enhanced Stability**: Risk mitigation through targeted deployment and easy rollback
* **Flexible Development**: Support for parallel development streams and testing scenarios
* **User-Centric Control**: Granular policy management at the user and group level
* **Priority Management**: Clear resolution when multiple policies could apply

## Permissions and access control

Active Policy management requires appropriate permissions to ensure secure and controlled access to policy configuration.

<Warning>
  Access to Active Policy settings should be strictly controlled as changes can affect production environments and user experience.
</Warning>

### Required permissions

* **View Active Policy**: Required to view current global policy and policy overrides
* **Manage Global Policy**: Required to modify the global active policy settings
* **Manage Policy Overrides**: Required to create, edit, activate/deactivate, and delete policy overrides
* **Admin Access**: Full access to all active policy features and settings

### Permission enforcement

* Unauthorized actions are blocked with clear denial messages
* All policy changes are audited with user identification and timestamps
* Role-based access ensures users can only perform actions within their authorization level

<Info>
  Contact your system administrator if you need additional permissions to manage active policies.
</Info>

## Technical details

### Policy resolution hierarchy

When a user accesses the runtime environment, the system resolves their active policy using this hierarchy:

1. **Username overrides** (highest priority)
2. **Group overrides** (if no username override exists; lowest priority number wins when several groups match)
3. **Global policy** (default fallback)

Legacy role overrides are skipped at this stage regardless of their saved priority.

### Priority-based override resolution

* When multiple group overrides could apply to a user, the override with the lowest priority number takes precedence
* Username overrides always take precedence over group overrides regardless of priority
* Priority numbers must be unique for group overrides on the same project and are mandatory
* Priority is particularly important when users belong to multiple groups, ensuring deterministic policy resolution
* Priority numbers help resolve conflicts when group membership overlaps

<Note>
  In scenarios where a user belongs to multiple groups (e.g., `developers` and `qa-testers`), the system uses the group override with the lowest priority number to determine their active policy.
</Note>

### Project context and resource references

* The active policy system determines how resource references are handled during process execution
* At runtime, the system identifies the active build based on the resolved policy for each user
* Ensures correct resource definitions are used based on user-specific or global policies

### Metadata and versioning

* Each policy (global and overrides) includes comprehensive metadata:
  * Build ID and version tags
  * Branch references and commit information
  * User/group assignments and priority settings
  * Creation and modification timestamps

### Audit and monitoring

* All policy changes are logged with detailed audit information:
  * User performing the action
  * Timestamp of the change
  * Before and after values
  * Action type (create, update, delete, activate, deactivate)
* Audit logs are accessible to authorized users for compliance and troubleshooting

### Storage and management

* Active policies and overrides are stored separately from build data
* Policy changes don't affect build integrity
* Efficient policy resolution at runtime with minimal performance impact
* Scalable architecture supports complex override scenarios

## Example use cases

### Scenario 1: Feature testing with user overrides

A development team collaborates on a project where all features are merged into the `main` branch.

To support this workflow, set a policy override for each developer, pointing to the feature branch they are currently working on. When a developer merges their branch, update their override to either deactivate it or assign it to their next active feature branch. This approach ensures developers can test their work in isolation without impacting the main environment or other users.

<Steps>
  <Step title="Set Global Policy">
    Set the global policy to use the latest build on the `main` branch. This ensures all users without overrides receive the most up-to-date production version by default.
  </Step>

  <Step title="Set User-Specific Policy Override">
    Set a policy override for each developer, assigning it to the feature branch they are currently working on:

    * **Override Type**: User
    * **Applies To**: Individual developer (e.g., `alice@company.com`)
    * **Policy**: Latest on Branch
    * **Branch**: Developer's active feature branch (e.g., `feature/alice-new-payment-flow`)
    * **Priority**: 1

    When a developer merges their branch, update their override to either:

    * **Deactivate** the override if no new feature branch is active, or
    * **Reassign** the override to the next feature branch they are working on

    This approach ensures each developer can test their changes independently, and their override always reflects their current work.
  </Step>

  <Step title="Test Independently">
    Developers can now test the new feature while production users continue using the stable build.

    <Check>
      No impact on production users during feature development and testing.
    </Check>
  </Step>
</Steps>

### Scenario 2: Gradual rollout with priority management

Rolling out a new version to different user groups:

<Steps>
  <Step title="QA Testing Override">
    Create high-priority override for the QA team:

    * **Override Type**: Group
    * **Applies To**: `qa-testers`
    * **Policy**: Build `v2.2.0-rc1`
    * **Priority**: 0 (highest)
  </Step>

  <Step title="Beta User Override">
    Create an override for beta users:

    * **Override Type**: Group
    * **Applies To**: `beta-users`
    * **Policy**: Build `v2.2.0-rc1`
    * **Priority**: 1
  </Step>

  <Step title="Production Rollout">
    After successful testing, update the global policy to `v2.2.0` and remove overrides.

    <Check>
      Controlled rollout minimizes risk and ensures thorough testing.
    </Check>
  </Step>
</Steps>

<Info>
  Runtime groups are managed in **Runtime Access Settings** and are shared across projects. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization) for how groups are created and how they receive runtime roles on each project.
</Info>

### Scenario 3: Emergency rollback

Quickly roll back from a problematic build by downgrading the global active policy:

<Steps>
  <Step title="Identify Issue">
    A critical issue is discovered in the current production build `v2.3.0`.
  </Step>

  <Step title="Downgrade Global Policy">
    Update the global active policy to point to the previous stable build (e.g., `v2.2.5`).

    <Check>
      All users will immediately use the stable build, ensuring a consistent and safe rollback.
    </Check>
  </Step>

  <Step title="Restore Latest Version">
    After resolving the issue, update the global policy to the new stable build (e.g., `v2.3.1` or a fixed `v2.3.0`).
  </Step>
</Steps>

<Tip>
  For emergency rollbacks, prefer downgrading the global active policy instead of using overrides. This approach is simpler, avoids confusion, and ensures all users are aligned on the same stable version.
</Tip>

## Conclusion

The Active Policy feature in FlowX.AI provides comprehensive control over project version management through both global policies and granular policy overrides. This dual-layer approach enables:

* **Flexible Testing**: Independent testing of different builds and branches by different user groups
* **Controlled Deployment**: Gradual rollouts with priority-based conflict resolution
* **Enhanced Stability**: Quick rollback capabilities and isolated testing environments
* **User-Centric Management**: Granular control at both user and group levels

By combining global policies with targeted overrides, Active Policy ensures that the right users access the right project versions at the right time, making it an essential tool for modern development and deployment workflows.

<Tip>
  Start with simple global policies and gradually introduce overrides as your testing and deployment needs become more complex.
</Tip>


# Failed process start (exceptions)
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/failed-process-start

View and debug exceptions that occur when process instances fail to start, including detailed error information and stack traces.

Exceptions are types of errors meant to help you debug a failure in the execution of a process.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/exceptions1.png)
</Frame>

Exceptions can be accessed from multiple places:

* **Failed process start** tab from **Active process** menu in FlowX.AI Designer.
* **Process Status** view, accessible from **Process instances** list in FlowX.AI Designer.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/exceptions2.png)
</Frame>

<Hint>
  If you open a process instance and it does not contain exceptions, the **Exceptions** tab will not be displayed.
</Hint>

### Exceptions data

When you click **view** button, a detailed exception will be displayed.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/exceptions_data.png)
</Frame>

* **Process Definition**: The process where the exception was thrown.
* **Source**: The source of the exception (see the possible type of [sources](#possible-sources) below).
* **Message**: A hint type of message to help you understand what's wrong with your process.
* **Type**: Exception type.
* **Cause Type**: Cause type (or the name of the node if it is the case).
* **Process Instance UUID**: Process instance unique identifier (UUID).
* **Token UUID**: The token unique identifier.
* **Timestamp**: The default format is - `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
* **Details**: Stack trace (a **stack trace** is a list of the method calls that the process was in the middle of when an **Exception** was thrown).

#### Possible sources

<CardGroup>
  <Card title="Actions" href="../../../building-blocks/actions/actions" />

  <Card title="Node" href="../../../building-blocks/node/node" />

  <Card title="Subprocess" href="../../../building-blocks/process/subprocess" />

  <Card title="Process Definition" href="../../../building-blocks/process/process-definition" />
</CardGroup>

### Exceptions type

Based on the exception type, there are multiple causes that could make a process fail. Here are some examples:

| Type                     | Cause                                                                                                                                                                                                              |
| :----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Business Rule Evaluation | When executing action rules fails for any reason.                                                                                                                                                                  |
| Condition Evaluation     | When executing action conditions.                                                                                                                                                                                  |
| Engine                   | <p /><p>When the connection with the database fails</p><p>when the connection with [Redis](../../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis) fails</p><p /> |
| Definition               | Misconfigurations: process def name, subprocess parent process id value, start node condition missing.                                                                                                             |
| Node                     | When an outgoing node can’t be found (missing sequence etc).                                                                                                                                                       |
| Gateway Evaluation       | <p>When the token can’t pass a gateway for any reason, possible causes:</p><ul><li>Missing sequence/node</li><li>Failed node rule</li></ul>                                                                        |
| Subprocess               | Exceptions will be saved for them just like for any other process, parent process ID will also be saved (we can use this to link them when displaying exceptions).                                                 |


# Process instance
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/process-instance

A process instance is a specific execution of a business process that is defined on the FlowX.AI platform. Once a process definition is added to the platform, it can be executed, monitored, and optimized by creating an instance of the definition.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_instance.png)
</Frame>

## Overview

Once the desired processes are defined in the platform, they are ready to be used. Each time a process needs to be used, for example each time a customer wants to request a new credit card, a new instance of the specified process definition is started in the platform. Think of the process definition as a blueprint for a house, and of the process instance as each house of that type being built.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_instance_overview.png)
</Frame>

The **FlowX.AI Engine** is responsible for executing the steps in the process definition and handling all the business logic. The token represents the current position in the process and moves from one node to the next based on the sequences and rules defined in the exclusive gateways. In the case of parallel gateways, child tokens are created and eventually merged back into the parent token.

Kafka events are used for communication between FlowX.AI components such as the engine and integrations/plugins. Each event type is associated with a Kafka topic to track and orchestrate the messages sent on Kafka. The engine updates the UI by sending messages through sockets.

<Card title="More about Kafka" href="../../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts" />

## Checking the Process Status

To check the status of a process or troubleshoot a failed process, follow these steps:

1. Open **FlowX.AI Designer**.
2. Go to **Projects → Your Project → Runtime → Active Process → Process instances**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_status.png)
</Frame>

### Understanding the Process Status data

Understanding the various elements within process status data is crucial. Here's what each component entails:

* The **Status** field indicates the state of the process instance, offering distinct values:

| Status         | Indicates the state of the process instance. Offers distinct values:                                                                                                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **CREATED**    | Visible if there's an error during process creation. Displays as `STARTED` if there were no errors during creation.                                                                                                                        |
| **STARTED**    | Indicates the current running status of the process.                                                                                                                                                                                       |
| **DISMISSED**  | Available for processes with subprocesses, seen when a user halts a subprocess.                                                                                                                                                            |
| **EXPIRED**    | This status appears when the defined "expiryTime" expression in the process definition elapses since the process was initiated (`STARTED`).                                                                                                |
| **FINISHED**   | Signifies successful completion of the process execution.                                                                                                                                                                                  |
| **TERMINATED** | A termination request was sent to the instance through a Kafka process operation message. See [Task operations via Kafka](../../../platform-deep-dive/core-extensions/task-management/task-management-overview#available-operation-types). |
| **ON HOLD**    | Marks a state where the process is no longer editable.                                                                                                                                                                                     |
| **FAILED**     | Occurs if a CronJob triggers at a specific hour, and the instance isn't finished by then.                                                                                                                                                  |

## Process instance details

Click on a process instance to view the details.

* **Active process instance**: The UUID of the process instance, with a copy action available.
* **Variables**: Displayed as a tree view or a JSON view. You can modify the variables using the JSON editor (available for STARTED or ON HOLD process instances). Check [Update Process Variables](./update-process-variables) for more information.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/variables.png)
</Frame>

* **Tokens**: A token represents the state within the process instance and describe the current position in the process flow.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token.png)
</Frame>

<Info>
  For more information, see the [token documentation](../../../building-blocks/token).
</Info>

* **Subprocesses**: Displayed only if the current process instance generated a [subprocess](../../../building-blocks/process/subprocess) instance.
* **Exceptions**: Errors that let you know where the process is blocked, with a direct link to the node where the process is breaking for easy editing.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/process_exceptions.png)
</Frame>

<Info>
  For more information on exceptions, check the following section:

  [Exceptions](../active-process/failed-process-start)
</Info>

* **Audit Log**: The audit log displays events registered for process instances, tokens, tasks, and exceptions in reverse chronological order by timestamp.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/audit_log.png)
</Frame>

<Card title="Audit" href="../../../platform-deep-dive/core-extensions/audit" />

* **Workflows**: If process instance has a Start Workflow node, the workflow will be displayed here.

* **Trigger**: Displayed for process instances started by an event-based trigger (such as an email trigger). Shows the following details:

| Column           | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| **Trigger Type** | The type of trigger that started the instance (for example, Email Trigger, Microsoft Outlook) |
| **Trigger Name** | The name of the trigger data source                                                           |
| **Process Name** | The process definition that was started                                                       |
| **Timestamp**    | Date and time the trigger event occurred                                                      |

* **Notifications**: Displays email notifications sent from this process instance. The table includes the following columns:

| Column                | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| **Notification Type** | The type of notification sent                                                                   |
| **Status**            | Delivery status with color-coded indicators: green for `DELIVERED`, red for `FAILED` or `ERROR` |
| **Data Source Name**  | The email connection (data source) used to send the notification                                |
| **Template Name**     | The notification template used                                                                  |
| **Process Name**      | The process definition associated with the notification                                         |
| **Sent At**           | Date and time the notification was sent                                                         |

* **Documents**: Single source of truth for every document handled during the process instance, regardless of how it entered the process. Each row exposes tracking metadata and an inline preview, and any document can be downloaded directly from the tab. Sources covered:

  * End-user uploads via the file-upload component
  * Attachments forwarded from an [email trigger](../../../platform-deep-dive/integrations/email-trigger)
  * Files generated from HTML templates
  * Files produced by OCR processing
  * Files produced by AI workflow nodes (for example, [Document Generation](../../../../ai-platform/agent-builder/node-types#ai-document-operations))

### Color coding

In the **Process Status** view, some nodes are highlighted with different colors to easily identify any failures:

* **Green**: Nodes highlighted with green mark the nodes passed by the [token](../../../building-blocks/token).
* **Red**: The node highlighted with red marks the node where the token is stuck (process failure).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/color_coding.png)
</Frame>

## Starting a new process instance

To start a new process instance, a request must be made to the [FlowX.AI Engine](../../../platform-deep-dive/core-components/flowx-engine). This is handled by the web/mobile application. The current user must have the appropriate role/permission to start a new process instance.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/process_instance_diagram.png)
</Frame>

To be able to start a new process instance, the current user needs to have the appropriate role/permissions:

<Card title="Configuring access roles for processes" href="../../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes" />

When starting a new process instance, we can also set it to [inherit some values from a previous process instance](../../../platform-deep-dive/core-components/flowx-engine#orchestration).

## Troubleshooting possible errors

If everything is configured correctly, the new process instance should be visible in the UI and added to the database. However, if you encounter issues, here are some common error messages and their possible solutions:
Possible errors include:

| Error Message                                                      | Description                                                                                      |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| *"Process definition not found."*                                  | The process definition with the requested name was not set as published.                         |
| *"Start node for process definition not found."*                   | The start node was not properly configured.                                                      |
| *"Multiple start nodes found, but start condition not specified."* | Multiple start nodes were defined, but the start condition to choose the start node was not set. |
| *"Some mandatory params are missing."*                             | Some parameters set as mandatory were not included in the start request.                         |
| `HTTP code 403 - Forbidden`                                        | The current user does not have the process access role for starting that process.                |
| `HTTP code 401 - Unauthorized`                                     | The current user is not logged in.                                                               |


# Update process variables
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/update-process-variables

Modify process variables on active process instances to resolve production issues without restarts or backend intervention.

## Overview

Update Process Variables allows you to modify process variables on active process instances. You can edit, add, or delete variables on process instances with **Started** or **On Hold** status.

<Info>
  This feature is part of operational process instance management, allowing teams to resolve data issues without developer intervention.
</Info>

<Frame>
  ![Process Variables View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/modify_variables.png)
</Frame>

The editor provides:

* JSON syntax validation and formatting
* Edit, add, or delete operations on variables
* Automatic synchronization to Task Manager and Elasticsearch
* Audit logging with snapshots of previous values

***

## Features

### JSON editor

The JSON editor offers:

* JSON syntax validation
* Syntax highlighting
* Auto-formatting
* Error detection

<Frame title="Update Process Variables">
  ![Process Variables View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/json_editor1.png)
</Frame>

### Access points

Access the editor from two locations:

<Tabs>
  <Tab title="From Process Instances page">
    1. Navigate to **Processes** → **Active Process** → **Process instances**
    2. Click the contextual menu (three dots) on any process instance row
    3. Select **Modify Variables**
    4. The system navigates to the Process Instance page and opens the Variables tab in edit mode
  </Tab>

  <Tab title="From View process instance page">
    1. Open a specific process instance
    2. Select **Modify Variables** from the contextual menu in secondary navigation
    3. The Variables tab opens in edit mode
  </Tab>
</Tabs>

<Frame title="Update Process Variables">
  ![Process Variables View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/modify_variables.png)
</Frame>

### Dual view modes

Switch between two viewing modes for process variables:

* **Tree View** (existing): Hierarchical display of variables with expand/collapse

<Frame title="Tree View">
  ![Tree View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/tree_view.png)
</Frame>

* **JSON View**: Raw JSON format, editable when in edit mode

<Frame title="JSON View">
  ![JSON View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/json_view.png)
</Frame>

The Export button is available near the view dropdown for downloading process variables.

### Compare view

The compare view uses a Monaco diff editor to show side-by-side differences between the original and modified process variable values. This helps you review changes before saving.

| Feature                 | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| **Side-by-side diff**   | Original values on the left, modified values on the right |
| **Change highlighting** | Added, removed, and modified lines are color-coded        |
| **Toggle views**        | Switch between Edit and Compare modes while editing       |

To use the compare view:

1. Open the variables editor in **Edit mode**
2. Make your changes in the JSON editor
3. Toggle to **Compare** view to see a diff of your modifications against the original values
4. Switch back to **Edit** view to continue making changes, or click **Save** to apply

<Tip>
  Use the compare view before saving to verify that only the intended variables were modified, especially when editing large JSON structures.
</Tip>

### Operations

You can:

* Edit existing attribute values
* Add new attributes or objects
* Delete existing attributes or objects

All operations are performed in the JSON editor with validation before saving.

***

## Access requirements

<Steps>
  <Step title="Check permissions">
    Ensure you have the `process_variables_edit` permission at the workspace level.

    <Info>
      The Edit option is only visible to users with this permission.
    </Info>
  </Step>

  <Step title="Navigate to process instance">
    Access from either:

    * Process Instances list → contextual menu
    * Process Instance detail page → secondary navigation
  </Step>

  <Step title="Open Variables tab">
    Click **Edit Variables** from the contextual menu. The Variables tab opens in edit mode.
  </Step>
</Steps>

***

## Editing process variables

<Steps>
  <Step title="Select active instance">
    Choose an active process instance with **Started** or **On Hold** status.

    <Warning>
      Only process instances in Started or On Hold status can have their variables modified.
    </Warning>
  </Step>

  <Step title="Switch to JSON View">
    In the Variables tab, switch from **Tree View** to **JSON View** using the view dropdown selector.
  </Step>

  <Step title="Enable edit mode">
    Click the **Modify Variables** button to make the JSON editor editable.

    <Info>
      This button is only visible if you have the necessary permissions.
    </Info>

    <Frame title="JSON editor in edit mode">
      ![JSON editor in edit mode](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/edit_mode.png)
    </Frame>
  </Step>

  <Step title="Modify variables">
    Edit process variables in the JSON editor:

    **Example - Editing existing values:**

    ```json theme={"system"}
    {
      "application": {
        "customer": {
          "id": "12345",
          "name": "John Doe",
          "email": "john.doe@example.com"
        },
        "status": "approved"
      }
    }
    ```

    **Example - Adding new attributes:**

    ```json theme={"system"}
    {
      "application": {
        "customer": {
          "id": "12345",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "phoneNumber": "+1234567890"
        },
        "status": "approved",
        "creditScore": 750
      }
    }
    ```

    **Example - Deleting attributes:**

    Remove unwanted attributes by deleting their lines from the JSON.
  </Step>

  <Step title="Validate JSON">
    Ensure your JSON format is valid before saving.

    <Warning>
      You cannot save if the JSON format is invalid. The JSON editor will highlight syntax errors automatically.
    </Warning>

    <Frame title="JSON validation errors">
      ![JSON validation errors](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/edit_errors.png)
    </Frame>

    **Common validation errors:**

    * Missing commas between properties
    * Unclosed brackets or braces
    * Missing quotes around strings
    * Trailing commas
  </Step>

  <Step title="Save changes">
    Click **Save** to apply your changes.

    The system automatically:

    * Creates a snapshot of previous values in a new table
    * Updates the process instance variables
    * Syncs to Task Manager (using existing mechanisms)
    * Updates Elasticsearch (for variables configured for data search)
    * Records the modification in the audit log
  </Step>

  <Step title="Review audit log">
    Navigate to the **Audit Log** tab to confirm the modification was recorded with all details.
  </Step>
</Steps>

***

## Permissions and security

<Info>
  **Access control:** This feature requires the workspace-level permission `wks_process_instance_variables_edit` (permission name: `process_variables_edit`). Users with this permission can edit and save variables; others can only view variables in read-only mode. By default, `ORG_ADMIN` and `WORKSPACE_ADMIN` roles include this permission.

  **Security features:** All modifications are logged in the audit trail with user identity and timestamp. Previous values are preserved in snapshot history before changes are applied. JSON syntax validation prevents data corruption.

  For more information about permissions, roles, and access management, see [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) and the [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide).
</Info>

***

## Data synchronization

### Updated automatically

When you modify process variables, the following are updated:

<CardGroup>
  <Card title="Process instance parameters" icon="database">
    Variables are updated immediately in the database
  </Card>

  <Card title="Task Manager" icon="tasks">
    Variables sync using existing mechanisms; task keywords and data remain consistent
  </Card>

  <Card title="Elasticsearch" icon="magnifying-glass">
    Variables configured for data search are updated automatically
  </Card>

  <Card title="Snapshot table" icon="camera">
    Previous values are saved in a snapshot table before changes are applied
  </Card>
</CardGroup>

### Not updated

The following are preserved to maintain data integrity:

<CardGroup>
  <Card title="Process snapshots" icon="x">
    Snapshots used for back navigation (Reset process data) remain unchanged
  </Card>

  <Card title="Debug records" icon="x">
    Process instance debug records preserve execution history as it occurred
  </Card>

  <Card title="Existing audit logs" icon="x">
    Previously recorded audit logs (manual actions, integrations) are not modified
  </Card>

  <Card title="Subprocess variables" icon="x">
    Child subprocess variables are not updated; parent changes don't cascade to children
  </Card>
</CardGroup>

### Synchronization details

#### Task manager sync

<Expandable title="How it works">
  * Uses existing Task Manager synchronization mechanisms
  * Updates task keywords if variables are configured as keywords
  * Maintains task searchability and filtering
</Expandable>

<Expandable title="What gets synced">
  * Task data fields mapped to process variables
  * Search keywords derived from variables
  * Custom task metadata
</Expandable>

<Expandable title="Timing">
  * Synchronization happens immediately after save
  * Typically completes within seconds
  * No manual intervention required
</Expandable>

#### Elasticsearch sync

<Expandable title="How it works">
  * Automatically updates Elasticsearch indexes
  * Only affects variables configured for data search
  * Uses existing indexing mechanisms
</Expandable>

<Expandable title="What gets synced">
  * Variables marked for Elasticsearch indexing
  * Data search fields
  * Process instance searchable data
</Expandable>

<Expandable title="Timing">
  * Index update happens immediately
  * Index refresh typically within seconds
  * Search availability may have slight delay
</Expandable>

***

## Audit logging

Every process variable modification creates a detailed audit log entry. Audit logs are displayed in the **Audit Log** tab within the process instance (in the **Runtime** -> **Active Process** -> **Process Instance** page).

<Steps>
  <Step title="Open process instance">
    Navigate to the process instance that was modified.
  </Step>

  <Step title="Go to Audit Log tab">
    Click the **Audit Log** tab to view all events for this instance.
  </Step>

  <Step title="Find modification entry">
    Look for entries with Event = "Update and Subject = "Process variables".

    <Frame title="Audit log edit entry">
      ![Audit log edit entry](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pv_audit.png)
    </Frame>
  </Step>

  <Step title="Review details">
    Click on the audit log entry to see:

    * Complete Body JSON
    * URL

    <Frame>
      ![Audit log edit entry](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pv_audit_body.png)
    </Frame>
  </Step>
</Steps>

***

## Important considerations

### Subprocess impact

<Warning>
  **Limitation:** When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are **not propagated** to existing subprocesses.
</Warning>

<Expandable title="Why this happens">
  * Each subprocess receives a copy of variables at start time
  * Subprocesses execute independently with their own variable context
  * Modifying parent variables doesn't trigger subprocess updates
</Expandable>

<Expandable title="Impact">
  * Parent and child processes may have inconsistent data
  * Subprocess logic executes based on original values
  * Manual coordination needed if subprocess data must match
</Expandable>

<Expandable title="Recommendation">
  * Understand parent-child relationships before modifying variables
  * Consider if subprocess data consistency is critical
  * Document any intentional data divergence
  * Test subprocess behavior after parent modifications
</Expandable>

### Back navigation

<Warning>
  **Limitation:** Process snapshots used for "Allow back to this action" with "Reset process data" are **not updated**. Users navigating back will see original values, not modified ones.
</Warning>

<Expandable title="Why this happens">
  * Snapshots preserve process state at specific points in time
  * Back navigation restores from these historical snapshots
  * Modified variables exist only in the current state
</Expandable>

<Expandable title="Impact">
  * Back navigation reverts to pre-modification values
  * User changes after modification may conflict
  * Process flow may not reflect recent modifications
</Expandable>

<Expandable title="Recommendation">
  * Use cautiously on processes with back navigation enabled
  * Warn users if back navigation is available
  * Consider disabling back navigation for affected nodes
  * Document this behavior for operations team
</Expandable>

### Integration messages

<Warning>
  **Limitation:** If a token is waiting for an integration message, the integration was called with original values. Modifying variables after integration calls **does not re-trigger** integrations.
</Warning>

<Expandable title="Why this happens">
  * Integrations are called with specific parameters
  * External systems process requests independently
  * Responses are based on original request data
</Expandable>

<Expandable title="Impact">
  * Integration responses won't reflect modified variables
  * Modified variables won't affect pending integration results
  * Data mismatch possible between integration and process
</Expandable>

<Expandable title="Recommendation">
  * Avoid modifying variables while waiting for integration responses
  * Consider re-executing nodes if integration data needs updating
  * Understand which variables were sent to integrations
  * Test integration scenarios carefully
</Expandable>

### Process instance debug table

**Not updated:** the process instance debug table records remain unchanged.

**Reason:** debug records capture execution history as it occurred. Modifying them would compromise debugging and troubleshooting capabilities.

***

## Best practices

### When to use

<CardGroup>
  <Card title="Correct user input errors" icon="check">
    Fix incorrect data submitted in forms
  </Card>

  <Card title="Unblock stuck instances" icon="check">
    Resolve missing data preventing continuation
  </Card>

  <Card title="Fix integration data issues" icon="check">
    Correct incorrect responses from external systems
  </Card>

  <Card title="Add missing attributes" icon="check">
    Add required data not collected initially
  </Card>

  <Card title="Remove invalid data" icon="check">
    Clean up test or incorrect data
  </Card>

  <Card title="Update search keywords" icon="check">
    Correct Task Manager search data
  </Card>

  <Card title="Fix Elasticsearch data" icon="check">
    Ensure accurate search results
  </Card>
</CardGroup>

### When not to use

<CardGroup>
  <Card title="Regular operational updates" icon="x">
    Design proper process flows instead
  </Card>

  <Card title="Subprocess coordination" icon="x">
    Parent-child sync not supported
  </Card>

  <Card title="Complex back navigation flows" icon="x">
    Snapshots won't reflect changes
  </Card>

  <Card title="While waiting for integrations" icon="x">
    Responses based on original values
  </Card>

  <Card title="Routine data corrections" icon="x">
    Indicates process design issues
  </Card>

  <Card title="Automated scripts" icon="x">
    Use process design and actions instead
  </Card>
</CardGroup>

### Validation before saving

<CardGroup>
  <Card title="Verify JSON syntax" icon="code">
    Ensure valid JSON format to prevent data corruption and save failures
  </Card>

  <Card title="Review impact" icon="list-check">
    Understand which variables you're changing and their impact on process flow
  </Card>

  <Card title="Check dependencies" icon="diagram-project">
    Review process flow, subprocesses, and integrations before modifying critical variables
  </Card>

  <Card title="Document changes" icon="book">
    Audit logs record changes automatically, but document why changes were made
  </Card>
</CardGroup>

***

## Common use cases

### 1. Correct user input errors

**Scenario:**\
Customer submitted incorrect loan data (wrong income amount, invalid address, incorrect contact information).

**Solution:**

1. Navigate to the process instance
2. Access Variables tab in edit mode
3. Locate the incorrect values in JSON
4. Correct the data:
   ```json theme={"system"}
   {
     "application": {
       "income": 75000,  // Changed from 50000
       "address": "123 Main St, New York, NY 10001"  // Corrected
     }
   }
   ```
5. Save changes
6. Process continues without requiring customer to restart the process

***

### 2. Unblock stuck process instances

**Scenario:**\
Process is waiting for external data that never arrives due to integration timeout or external system being down indefinitely.

**Solution:**

1. Identify the variable causing the blockage
2. Open process variables in edit mode
3. Update the variable to provide expected data or bypass condition:
   ```json theme={"system"}
   {
     "integration": {
       "responseReceived": true,  // Manually set to true
       "creditCheckStatus": "completed"  // Provide expected value
     }
   }
   ```
4. Save changes
5. Instance unblocks and continues execution

***

### 3. Fix integration data issues

**Scenario:**\
External credit check system returned incorrect or incomplete data due to system error.

**Solution:**

1. Review the integration response variables
2. Edit variables to correct the data:
   ```json theme={"system"}
   {
     "creditCheck": {
       "score": 720,  // Corrected from incorrect 520
       "status": "approved",  // Fixed status
       "provider": "ExternalCreditBureau"
     }
   }
   ```
3. Save changes
4. Process continues with accurate data

***

### 4. Add missing attributes

**Scenario:**\
Process needs additional data that wasn't collected at start time, but is now required for a decision point.

**Solution:**

1. Access process variables
2. Add new required attributes:
   ```json theme={"system"}
   {
     "application": {
       "existingField": "value",
       "newlyRequiredField": "new value",  // Added
       "additionalData": {  // Added entire object
         "field1": "value1",
         "field2": "value2"
       }
     }
   }
   ```
3. Save changes
4. Process can now access the missing data at decision points

***

### 5. Delete invalid data

**Scenario:**\
Process contains test data or incorrect objects that shouldn't be there and are causing validation failures.

**Solution:**

1. Open process variables
2. Remove problematic data:
   ```json theme={"system"}
   {
     "application": {
       "validData": "correct value"
       // Removed "testData": {...}
       // Removed "invalidObject": {...}
     }
   }
   ```
3. Save changes
4. Process continues with clean, valid data only

***

### 6. Update task manager keywords

**Scenario:**\
Task search keywords need updating based on corrected customer data for better task discoverability.

**Solution:**

1. Modify variables that are configured as Task Manager keywords:
   ```json theme={"system"}
   {
     "customer": {
       "name": "Jane Smith",  // Corrected
       "accountNumber": "ACC-98765",  // Updated
       "status": "active"
     }
   }
   ```
2. Save changes
3. System automatically syncs to Task Manager
4. Tasks become searchable with correct keywords

***

### 7. Fix Elasticsearch search data

**Scenario:**\
Process data indexed for search contains errors, making instances unsearchable or showing in wrong search results.

**Solution:**

1. Identify variables configured for Elasticsearch data search
2. Correct the values:
   ```json theme={"system"}
   {
     "searchableData": {
       "category": "loans",  // Corrected from "loans_test"
       "priority": "high",  // Fixed
       "customerSegment": "premium"  // Updated
     }
   }
   ```
3. Save changes
4. Elasticsearch automatically updates
5. Process instances appear in correct search results

***

### 8. Emergency business rule changes

**Scenario:**\
Regulatory change requires immediate update to pricing or terms in active applications.

**Solution:**

1. Access affected process instances
2. Update variables to reflect new business rules:
   ```json theme={"system"}
   {
     "pricing": {
       "interestRate": 3.5,  // Updated per regulation
       "fees": {
         "processing": 50,  // Adjusted
         "regulatory": 25   // New fee added
       }
     }
   }
   ```
3. Save changes for all affected instances
4. Processes continue with compliant data

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Edit button not visible">
    **Symptoms:**

    * Cannot see Edit option in contextual menu
    * Variables tab shows read-only view only

    **Possible causes:**

    * User doesn't have `process_variables_edit` permission
    * Process instance is not active (not Started or On Hold)
    * Wrong tab selected

    **Solutions:**

    1. Verify user has `process_variables_edit` permission:
       * Check workspace permissions
       * Confirm user role includes this permission
       * Contact workspace administrator if needed

    2. Check process instance status:
       * Only Started or On Hold instances can be edited
       * Finished, Failed, or Terminated instances cannot be modified
       * Verify status in process instance details

    3. Ensure you're in Variables tab:
       * Switch to Variables tab if in another tab
       * Refresh the page if needed
  </Accordion>

  <Accordion title="Cannot save - JSON validation error">
    **Symptoms:**

    * Save button disabled or shows error
    * Red error indicators in editor
    * Error message: "Invalid JSON format"

    **Common JSON errors:**

    **Missing comma:**

    ```json theme={"system"}
    {
      "field1": "value1"  // ❌ Missing comma here
      "field2": "value2"
    }
    ```

    **Correct:**

    ```json theme={"system"}
    {
      "field1": "value1",  // ✅ Comma added
      "field2": "value2"
    }
    ```

    **Trailing comma:**

    ```json theme={"system"}
    {
      "field1": "value1",
      "field2": "value2",  // ❌ Trailing comma
    }
    ```

    **Unclosed brackets:**

    ```json theme={"system"}
    {
      "object": {
        "field": "value"
      // ❌ Missing closing }
    }
    ```

    **Solutions:**

    1. Use JSON editor error highlights to locate issues
    2. Copy JSON to external validator (jsonlint.com)
    3. Check for common issues: commas, brackets, quotes
    4. Validate structure matches JSON specification
    5. Remove trailing commas
    6. Ensure all brackets and braces are closed
  </Accordion>

  <Accordion title="Changes not reflected in Task Manager">
    **Symptoms:**

    * Task Manager still shows old values
    * Task search doesn't find with new keywords
    * Task data appears outdated

    **Possible causes:**

    * Task Manager sync delay
    * Variables not configured for Task Manager keywords
    * Task Manager service issues
    * Cache issues

    **Solutions:**

    1. Wait and refresh:
       * Wait 10-30 seconds for sync
       * Refresh Task Manager view
       * Clear browser cache if needed

    2. Verify configuration:
       * Check if variables are configured as task keywords
       * Review Task Manager configuration
       * Confirm variable mapping is correct

    3. Check system health:
       * Verify Task Manager service is running
       * Review sync logs for errors
       * Check Kafka messages if available

    4. Verify save completed:
       * Check audit log for successful save
       * Confirm no error messages appeared
       * Review process instance variables show new values
  </Accordion>

  <Accordion title="Elasticsearch search not showing updated data">
    **Symptoms:**

    * Search doesn't return expected results
    * Old values appear in search results
    * Process instance not found with new criteria

    **Possible causes:**

    * Elasticsearch sync delay
    * Variables not configured for data search
    * Index refresh delay
    * Elasticsearch service issues

    **Solutions:**

    1. Wait for index refresh:
       * Elasticsearch typically refreshes within seconds
       * Wait up to 1 minute for propagation
       * Try search again after waiting

    2. Verify configuration:
       * Check if variables are configured for Elasticsearch indexing
       * Review process definition for data search settings
       * Confirm variable paths match index mapping

    3. Check Elasticsearch health:
       * Verify Elasticsearch service is running
       * Check index status
       * Review indexing logs for errors

    4. Manual verification:
       * Query Elasticsearch directly if possible
       * Check index document for process instance
       * Verify field values match expected data
  </Accordion>

  <Accordion title="Modified variables lost after back navigation">
    **Symptoms:**

    * User navigates back in process
    * Variables revert to original values
    * Recent modifications disappeared

    **This is expected behavior - not a bug.**

    **Explanation:**
    Process snapshots used for back navigation are not updated when you modify variables. When users navigate backwards, the process state is restored from the snapshot, reverting to original values.

    **Why this happens:**

    * Snapshots preserve historical process state
    * Back navigation restores exact point-in-time state
    * Maintains integrity of back navigation feature

    **Recommendations:**

    1. **Document this behavior:**
       * Inform operations team about snapshot behavior
       * Add notes to operational procedures
       * Train users on implications

    2. **Prevent back navigation:**
       * Disable back navigation for nodes after modification
       * Configure "Allow back to this action" appropriately
       * Consider process design implications

    3. **Alternative approaches:**
       * Modify variables only when back navigation unlikely
       * Re-apply modifications after back navigation if needed
       * Design processes to minimize back navigation needs

    4. **User warnings:**
       * Display warnings before allowing back navigation
       * Inform users modifications may be lost
       * Provide clear guidance on expected behavior
  </Accordion>

  <Accordion title="Subprocess shows different data than parent">
    **Symptoms:**

    * Parent process variables updated
    * Subprocess still has old values
    * Data inconsistency between parent and child

    **This is expected behavior - not a bug.**

    **Explanation:**
    Subprocesses receive a copy of variables at start time and execute independently. Modifying parent variables doesn't cascade to existing child subprocesses.

    **Why this happens:**

    * Subprocesses have independent execution context
    * Each subprocess operates on its snapshot of data
    * Maintains process isolation and integrity

    **Solutions:**

    1. **Understand before modifying:**
       * Check if process has active subprocesses
       * Review parent-child data dependencies
       * Assess impact of data divergence

    2. **Manual coordination:**
       * Modify subprocess variables separately if needed
       * Document intentional data divergence
       * Test subprocess behavior with original values

    3. **Process design considerations:**
       * Design processes to minimize parent-child data coupling
       * Pass critical data as subprocess parameters
       * Use events for dynamic data synchronization
  </Accordion>

  <Accordion title="Integration response doesn't match modified data">
    **Symptoms:**

    * Integration called before modification
    * Response based on original values
    * Data mismatch between variables and integration result

    **This is expected behavior - not a bug.**

    **Explanation:**
    Integrations are called with specific parameters. External systems process requests independently. Modifying variables after the call doesn't re-trigger the integration or affect the response.

    **Why this happens:**

    * Integration already executed with original parameters
    * External system processed original request
    * Response is based on what was sent
    * Modifying variables is local to process instance

    **Solutions:**

    1. **Avoid modifying during integration:**
       * Check if token is waiting for integration response
       * Wait for integration to complete before modifying
       * Document which variables were sent to integration

    2. **Re-execute if needed:**
       * Consider re-executing the integration node
       * Manually trigger integration with new values if possible
       * Design retry mechanisms in process flow

    3. **Accept response:**
       * Use integration response as-is
       * Modify only non-integration-related variables
       * Document why integration response doesn't match
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Process Instance Overview" href="./process-instance" icon="diagram-project">
    Learn about process instances and execution
  </Card>

  <Card title="Process Status" href="./process-instance#checking-the-process-status" icon="chart-line">
    Monitor process execution and troubleshoot issues
  </Card>

  <Card title="Audit Logs" href="../../../platform-deep-dive/core-extensions/audit" icon="list-check">
    Understand audit logging and compliance tracking
  </Card>

  <Card title="Task Management" href="../../../platform-deep-dive/core-extensions/task-management/task-management-overview" icon="tasks">
    Learn about Task Manager integration
  </Card>
</CardGroup>


# Builds
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/builds

The Build feature allows for the creation of deployable packages of a project, encapsulating all its resources into a single unit.

A build is a snapshot of a specific project version, packaged and prepared for deployment to a runtime environment. The concept of builds plays a crucial role in ensuring that the correct version of a project, with all its configurations and dependencies, runs consistently across different environments (for example, Dev, UAT, Production).

<Info>
  You can create multiple versions of a project before creating a build. You can create a build for any committed project version. Once created, a build cannot be edited—you'll need to create a new project version and generate a new build to incorporate changes.
</Info>

#### Key concepts

1. **Project Version vs. Build**
   * **Project Version** is the editable snapshot of a project's state at a specific point in time. It contains all the resources (like processes, integrations, templates, etc.) and configurations grouped within the project.
   * A **Build** is the deployable package of a project version. It is the compiled and immutable state that contains all the project resources transformed into executable components for the runtime environment.

2. **Single Version Rule**
   * A build can only represent a single version of a project. If you have multiple versions of a project, each one can have a unique build. This ensures that you can clearly manage which version of the project is running in a specific environment without conflicts.

3. **Consistency and Deployment**
   * Builds ensure that when you deploy a project to a different environment (like moving from Dev to UAT), the exact configuration, processes, templates, integrations, and all associated resources remain consistent.
   * Builds are immutable—once created, a build cannot be altered. Any updates require creating a new version of the project and generating a new build.

### Creating a build

To create a build from a committed project version:

<Steps>
  <Step title="Navigate to Version Details">
    Access the version details panel for the committed version you want to build. You can only create builds from committed versions, not from draft (WIP) versions.
  </Step>

  <Step title="Open Create Build Dialog">
    Click the **Create Build...** button in the version details panel. This opens the build creation modal.

    <Frame>
      ![Create Build](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build.png)
    </Frame>
  </Step>

  <Step title="Configure Build Settings">
    In the **Create build** modal, configure the following settings:

    * **Name**: The build name (defaults to the project name). This helps identify the build in the builds list.
    * **Build Tag Version**: Set the semantic version for this build:
      * **Major**: Major version number (for example, `1`)
      * **Minor**: Minor version number (for example, `0`)
      * **Patch**: Patch version number (for example, `0`)

    The build tag follows semantic versioning format (for example, `1.0.0`) and helps track different builds of the same project version.
  </Step>

  <Step title="Save the Build">
    Click **Save** to create the build. The build is now available in the Builds section and can be deployed to runtime environments.
  </Step>
</Steps>

<Frame>
  ![Create Build Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build_modal.png)
</Frame>

### Build immutability

Once a build is created, it becomes immutable—you cannot modify its contents. This ensures:

* **Consistency**: The same build behaves identically across all environments
* **Traceability**: You can always identify exactly which project version is running
* **Stability**: Prevents accidental changes that could affect production systems

To incorporate changes into a build:

1. Make your changes in the project (creating a new draft version)
2. Commit the changes to create a new project version
3. Create a new build from the updated committed version

### Key features

1. **Checksum and Integrity**
   * Each build includes a checksum or identifier to verify its integrity. This ensures that the deployed build matches the expected configuration and no changes have been made post-build.

2. **Runtime Dependency**
   * The runtime environment relies on builds to determine the active project configuration. This means the runtime does not directly interact with the editable project versions but uses builds to maintain stability and reliability.

3. **Version Control**
   * Builds are version-controlled, and each build corresponds to a specific project version. This means you can trace exactly which project configuration is active in a particular environment at any time.

#### Benefits

* **Consistency Across Environments**: Builds ensure that the same version of an project runs in different environments, avoiding discrepancies between development and production.
* **Reduced Errors**: Immutable builds reduce the risk of runtime errors caused by unexpected changes.
* **Simplified Rollbacks**: If an issue is detected with a current build, previous builds can be deployed quickly, providing an efficient rollback strategy.
* **Simplified Deployment**: Builds allow for a straightforward deployment process, reducing the complexity of transferring configurations and resources between environments.

### Managing builds

The **Builds** section provides a centralized interface for viewing and managing all builds for your project. Access this section by navigating to your project, switching to **Runtime** mode, and selecting **Builds** from the navigation menu.

<Frame>
  ![Builds Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/builds_interface.png)
</Frame>

#### Builds list

The builds list displays all builds created for the project, showing:

* **Build name and version**: Displays the build name and tag version (for example, `Update_process_variables 1.0.0`)
* **Build actions**: Each build entry provides quick access to:
  * **Play/Run**: Test the build with options to:
    * Test build
    * Test endpoint
    * Test workflow
    * Test operation
  * **Export**: Export the build for transfer to other environments or workspaces
  * **More options**: Additional actions via the context menu:
  <Frame>
    ![Build Actions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/builds_ctx.png)
  </Frame>
  * View contents
  * Workflow test instances
  * Audit log
  * Apply indexes
  * Drop indexes

#### Apply indexes

Indexes defined on [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) collections during config time are not automatically applied to the actual MongoDB database. To apply them, use the **Apply Indexes** action from the build's context menu (**More options → Apply Indexes**).

Indexes are applied from the build's snapshot, not from your current configuration. If you add or change indexes, create a new build to capture them and run **Apply Indexes** on that build. If the indexes are unchanged, you don't need to re-apply them for every new build — once applied, they stay on the database until you change them or use **Drop Indexes**.

<Info>
  * Only **one build** per project or library can have indexes applied at a time.
  * Applying indexes on a new build **replaces** any previously applied indexes that differ from those in the new build.
  * To remove all applied indexes from a build, use **Drop Indexes** from the same menu. Dropping indexes may impact existing query performance.
</Info>

#### Searching builds

Use the **Search by build tag** field to quickly find specific builds by their version tag or name. This is particularly useful when managing multiple builds for the same project.

### Exporting builds

You can export builds directly from the **Builds** section. This is useful when you want to transfer a specific build (rather than a version) between environments or workspaces.

<Steps>
  <Step title="Navigate to Builds Section">
    1. Open **FlowX.AI Designer** and go to the **Projects** section
    2. Select your project and navigate to **Runtime** and then to the **Builds** section
  </Step>

  <Step title="Select Build to Export">
    1. Locate the build you want to export in the builds list
    2. Click the **Export** icon (box with upward arrow) for the desired build
  </Step>

  <Step title="Complete Export">
    The build export follows the same process as version export, including the binary files option. The exported build can be imported into other environments or workspaces.
  </Step>
</Steps>

<Info>
  For detailed information about importing exported builds, see the [Export/Import documentation](../flowx-designer/managing-a-project-flow/export-import-a-process-definition).
</Info>

### Technical details

1. **Manifest and Metadata**
   * Each build contains a manifest that lists all the resources included, their version IDs, and their resource definitions.
   * Metadata helps identify which project version the build is derived from, providing traceability.

2. **Separation of Design and Runtime**
   * Builds serve as a bridge between the design (config) view and the runtime view. The config view is where changes are made and managed, while the runtime view uses builds to execute stable, tested versions of projects.

3. **Storage**
   * Builds are stored in a dedicated storage system to ensure they are separate from the editable project versions. This storage supports easy retrieval and deployment of builds.

#### Example use case

Imagine you have a project for customer onboarding with multiple processes, templates, and integrations. After completing development and final testing, you:

* Submit changes to create **Version 1.0** of the project.
* Create a build for **Version 1.0**.
* Deploy this build to the UAT environment for final stakeholder review.
* If any adjustments are needed, you go back to the project, make changes, and submit them as **Version 1.1**.
* Create a new build for **Version 1.1**, ensuring that the changes are encapsulated separately from the previous version.

Once everything is approved, you can publish **Version 1.1 Build** to the Production environment, ensuring all environments are aligned without manual reconfiguration.

#### Conclusion

The Build feature is essential for managing projects across multiple environments. It provides a clear and organized pathway from development to deployment, ensuring consistency, integrity, and stability throughout the project's lifecycle.


# Configuration parameters overrides
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/configuration-parameters-overrides

The Configuration parameters overrides feature allows you to set environment-specific values for certain parameters within a project.

This features enables flexibility and customization, making it possible to tailor a project’s behavior and integration settings according to the needs of each environment (e.g., Dev, UAT, Production). By defining overrides, you can manage variables like API endpoints, authentication tokens, environment-specific URLs, and other settings without altering the core project configuration.

#### Key concepts

1. **Configuration Parameters**
   * Configuration parameters are placeholders used throughout a project to store key settings and values. These parameters can include anything from URLs, API keys, and credentials to integration-specific details.
   * Parameters can be defined at the project level and referenced throughout processes, business rules, integrations, and templates.

<Info>
  If an override is needed for a configuration parameter defined in a library, it must be applied within the project where the library is used as a dependency. This ensures a clear distinction between library defaults and project-specific configurations while maintaining flexibility.

  Overrides applied in a project take precedence over the values defined in the library.
</Info>

2. **Environment Overrides**
   * Overrides are specific values assigned to configuration parameters for a particular environment. This ensures that a project behaves appropriately for each environment without requiring changes to the project itself.
   * Each environment (Development, UAT, Production) can have a unique set of overrides that replace the default parameter values when the project is deployed.

3. **Variable Precedence**

* Process Variables Override Configuration Parameters:
  * If a process variable and a configuration parameter share the same name, the process variable takes precedence at runtime.
  * If the process variable is null or undefined, the configuration parameter’s value is used as a fallback.
* Best Practice: Avoid naming process variables the same as configuration parameters to prevent unexpected overrides or conflicts.

4. **Centralized Management**
   * Configuration parameters and their overrides are managed centrally within the project’s settings. This allows for quick adjustments and a clear overview of how each environment is configured.

#### Workflow for managing Configuration parameter overrides

1. **Defining Configuration Parameters**
   * Go to the project settings and navigate to the **Configuration Parameters** section.
   * Define parameters that will be used across the project, such as:
     * **CRM URL**: Base URL for CRM integration.
     * **API Key**: Secure key for external service authentication.
     * **Environment URL**: Different base URLs for various environments (Dev, UAT, Production).

2. **Setting Up Environment-Specific Overrides**
   * Access the **Overrides** section for configuration parameters.
   * For each environment (e.g., Dev, UAT), assign specific values to the defined parameters. For example:
     * Dev Environment: `CRM_URL` → `https://dev.crm.example.com`
     * UAT Environment: `CRM_URL` → `https://uat.crm.example.com`
   * Save the environment-specific overrides. These values will take precedence over the default settings when deployed in that environment.

3. **Applying Overrides at Runtime**
   * When a project is deployed to a specific environment, the system automatically applies the relevant overrides.
   * Overrides ensure that the configuration aligns with environment-specific requirements, like endpoint adjustments or security settings, without altering the core setup.

#### Key features

1. **Flexibility Across Environments**
   * Easily adjust configuration parameters without changing the core application, ensuring that the project adapts to the target environment.

2. **Centralized Parameter Management**
   * Configuration parameters and their environment-specific overrides are managed centrally within the project settings, providing a single source of truth.

3. **Dynamic Integration Adaptation**
   * Environment-specific overrides allow integrations to connect to different endpoints or use different credentials based on the environment, supporting a smoother development-to-production workflow.

4. **Improved Security**
   * Sensitive data, such as API keys or credentials, can be stored as environment-specific overrides, ensuring that development and testing environments do not share the same sensitive values as production.

5. **Avoid Variable Naming Conflicts**
   * Best Practice: Use distinct names for process variables and configuration parameters to avoid unintentional overrides. If process variables are undefined or null, they will default to the corresponding configuration parameter’s value.

6. **Editor Autocomplete**
   * Monaco code editors in the Designer (Script nodes, Business Rules, workflow expressions) provide autocomplete suggestions from your project’s configuration parameters, reducing errors and speeding up development.

#### Benefits

* **Simplified Deployment**: Overrides eliminate the need for manual configuration changes during deployment, streamlining the process and reducing the risk of errors.
* **Environment Consistency**: Each environment can have its own tailored settings, ensuring consistent behavior and performance across all stages.
* **Secure Configuration**: Overrides keep sensitive parameters isolated to the appropriate environments, enhancing security and minimizing the risk of exposure.
* **Ease of Maintenance**: Centralized management of parameters and overrides simplifies adjustments when changes are needed, minimizing maintenance overhead.

#### Managing Configuration parameters overrides

1. **Creating a Parameter**
   * In the project settings, navigate to the **Configuration Parameters** section.
   * Define a new parameter by specifying its name, type, and default value.
   * This parameter will be used as a placeholder throughout the project, referenced in processes, templates, and integrations.

2. **Assigning Overrides**
   * Access the **Overrides** tab for the configuration parameters.
   * Choose the environment (e.g., Dev, UAT, Production) and assign a specific override value for each parameter.
   * Confirm the changes to apply the overrides for the selected environment.

3. **Viewing and Editing Overrides**
   * From the project’s settings, you can review all environment-specific overrides in one place.
   * Edit existing overrides or add new ones as needed to adapt to changes in environment requirements.

#### Technical details

1. **Parameter Resolution at Runtime**
   * During runtime, the system retrieves the active configuration parameters for the project. If overrides are set for the environment, they replace the default values.
   * This resolution ensures that the correct parameters are used, based on the environment in which the application is running.

2. **Integration with Business Rules and Processes**
   * Configuration parameters can be directly referenced in business rules and processes. Overrides ensure that these references point to the correct environment-specific values during execution.

<Info>
  For more information on how to use configuration parameters in business rules, see [Extracting values from configuration parameters](../../building-blocks/actions/business-rule-action/extracting-additional-data#extracting-values-from-configuration-parameters)
</Info>

3. **Storage and Management**
   * Configuration parameters and their overrides are stored centrally, and the values are retrieved dynamically during runtime. This centralized approach ensures that updates to parameters are automatically reflected in the application without needing a new build.

#### Example use case

Imagine you have an application that integrates with a third-party CRM system. You:

* Define a `CRM_URL` parameter with a default value for the development environment.
* Create overrides for UAT and Production environments with their respective URLs.
* When the application is deployed to the UAT environment, the system automatically uses the UAT-specific CRM URL for all integration points without changing the project’s core configuration.
* When it's time to deploy to Production, the system uses the production-specific overrides, ensuring that the application connects to the right CRM instance.


# Manage Triggers
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/manage-triggers

Monitor and control event-based triggers that automatically start process instances. Manage Triggers provides a centralized interface to view, activate, and deactivate triggers configured in your project builds.

## Overview

The **Manage Triggers** feature provides a centralized interface for monitoring and controlling event-based triggers that automatically start process instances. Triggers connect external events (such as email arrivals, message events, or other data sources) to your process definitions, enabling event-driven automation.

<Card title="Trigger Types" icon="bolt">
  Supported trigger types:

  * **Email Trigger** (IMAP): Start processes when emails arrive via [Email Trigger](../../docs/platform-deep-dive/integrations/email-trigger) data sources
  * **Microsoft Outlook** (MS Graph): Start processes when emails arrive via [Microsoft Outlook](../../docs/platform-deep-dive/integrations/microsoft-outlook-data-source) data sources
</Card>

<Frame>
  ![Manage Triggers Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/emt.png)
</Frame>

## Accessing manage triggers

Navigate to **Runtime Settings** → **Manage Triggers** from your project's Runtime view to access the triggers management interface.

<Info>
  You must have appropriate runtime permissions to view and manage triggers. See [Workspace runtime editor](/5.9/setup-guides/access-management/workspaces-access-rights#workspace-runtime-editor) for details.
</Info>

## Trigger list

The **Manage Triggers** interface displays all triggers configured in your active build. Each trigger appears as a row in the table with the following information:

| Column           | Description                                                                     |
| ---------------- | ------------------------------------------------------------------------------- |
| **State**        | Current status: `Active` (monitoring enabled) or `Inactive` (monitoring paused) |
| **Trigger Type** | The type of trigger (for example, "Email Trigger")                              |
| **Event Name**   | The name of the trigger data source or event configuration                      |
| **Location**     | Project and build information where the trigger is configured                   |

### Empty state

When no triggers are configured for your project, the interface displays an empty state message: **"There are no triggers on this project yet."**

Triggers appear in this list once:

1. ✅ A trigger data source is created (for example, Email Trigger in Integration Designer)
2. ✅ The trigger is linked to a Message Start Event node in a process definition
3. ✅ The process is included in a build that is part of the **Active Policy**

## Activating and deactivating triggers

You can control trigger monitoring directly from the **Manage Triggers** interface:

<Steps>
  <Step title="View triggers">
    Navigate to **Runtime Settings** → **Manage Triggers** to see all available triggers for your active build.
  </Step>

  <Step title="Toggle trigger state">
    Use the toggle control in the **State** column to activate or deactivate monitoring:

    * **Active**: The system monitors for events and creates process instances automatically
    * **Inactive**: Monitoring is paused; no new process instances are created from this trigger

    <Frame>
      ![Manage Triggers Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/emt1.pn§g)
    </Frame>
  </Step>
</Steps>

<Warning>
  When you change the **Active Policy** (switch to a different build), triggers retain their previous activation state. If a trigger is removed from the new active build, it will be automatically deactivated.
</Warning>

## Trigger activation requirements

For a trigger to appear in **Manage Triggers**, it must meet all of the following requirements:

1. **Trigger data source exists**: The trigger must be configured as a data source (for example, Email Trigger in Integration Designer)
2. **Linked to process**: The trigger must be connected to a Message Start Event node in a process definition
3. **In active build**: The process containing the trigger must be part of a build that is set as the **Active Policy**

<Info>
  Triggers are read-only in the Runtime view. To modify trigger configurations (for example, change email server settings, update filters), you must edit the data source in Integration Designer and create a new build.
</Info>

## Use cases

<CardGroup>
  <Card title="Email-based automation" icon="envelope">
    Automatically start customer support processes when emails arrive in monitored mailboxes. Email Triggers enable event-driven workflows for support ticket creation, document processing, and request handling.
  </Card>

  <Card title="Event-driven processes" icon="broadcast-tower">
    Connect external systems to FlowX processes through event triggers. When external events occur (emails, messages, API calls), processes start automatically without manual intervention.
  </Card>

  <Card title="Production control" icon="sliders">
    Pause or resume trigger monitoring in production environments without redeploying builds. This is especially useful for maintenance windows or when troubleshooting issues.
  </Card>

  <Card title="Multi-environment management" icon="layer-group">
    Manage trigger states independently across different environments (dev, staging, production) while using the same build configuration.
  </Card>
</CardGroup>

## Monitoring trigger activity

### Failed triggers

When triggers fail to process events (for example, email validation errors, connection issues), they appear in the **Failed Triggers** section.

Navigate to **Runtime Settings** → **Failed Triggers** to view:

* Timestamp of the failure
* Trigger type and name
* Cause type (for example, "File type not permitted," "File size exceeded")
* Context information (for example, sender email, file details)

<Card title="Failed Triggers Documentation" icon="exclamation-triangle" href="/5.9/docs/projects/runtime/active-process/failed-process-start">
  See the Failed Process Start documentation for details on handling trigger failures.
</Card>

## Best practices

<CardGroup>
  <Card title="Test before activation" icon="flask">
    Always test triggers in development environments before activating them in production. Verify that process instances start correctly and handle edge cases.
  </Card>

  <Card title="Monitor failed triggers" icon="chart-line">
    Regularly check the Failed Triggers section to identify and resolve issues. Common causes include file size limits, connection problems, and validation errors.
  </Card>

  <Card title="Use descriptive names" icon="tag">
    Give triggers descriptive names in Integration Designer to make them easily identifiable in the Manage Triggers list.
  </Card>

  <Card title="Document trigger behavior" icon="file-lines">
    Document which processes are triggered by each trigger and under what conditions. This helps with troubleshooting and maintenance.
  </Card>
</CardGroup>

## Related resources

<CardGroup>
  <Card title="Email Trigger" href="/5.9/docs/platform-deep-dive/integrations/email-trigger" icon="envelope">
    Learn how to configure Email Triggers in Integration Designer and connect them to Message Start Events.
  </Card>

  <Card title="Message Start Events" href="/5.9/docs/building-blocks/node/message-events/message-catch-start-event" icon="play">
    Understand how Message Start Events work and how to configure them in process definitions.
  </Card>

  <Card title="Active Policy" href="/5.9/docs/projects/runtime/active-policy" icon="sliders">
    Learn how to set the Active Policy to control which build's triggers are available for management.
  </Card>

  <Card title="Failed Process Start" href="/5.9/docs/projects/runtime/active-process/failed-process-start" icon="exclamation-triangle">
    Troubleshoot trigger failures and understand error handling for failed process starts.
  </Card>
</CardGroup>


# Scheduled processes
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/scheduled-processes

Automate process instance creation on specific dates, times, or intervals using Start Timer Event nodes and predefined schedules.

## Overview

The **Scheduled Processes** feature automatically triggers process instances using Timer Start Events. In the **Runtime** tab, you can view scheduled processes and activate/deactivate timers without a redeployment. This feature is especially useful in upper environments, where you might need to pause or resume cron jobs without modifying the project build.

<Card title="Timer Start Event" href="../../building-blocks/node/timer-events/timer-start-event" icon="file">
  Check this section for more details about Timer Start Events and how to configure them.
</Card>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)
</Frame>

## Key components

### 1. List of scheduled processes

The **Scheduled Processes** tab displays all timers that trigger process instances. Each row in the list shows:

* **Process Name:** The process linked to the timer.
* **Swimlane Name:** In multi-swimlane processes, each swimlane may have its own timer.
* **Timer Name:** The name of the timer node.
* **Timer Type:**
  * **Date-based:** Triggers at a specific date and time.
  * **Cycle-based:** Repeats at defined intervals (for example, every 10 seconds).
* **Location:** The execution environment (e.g., **Local**).

From this interface, you can view timer details or activate/deactivate timers as needed.

### 2. Timer Events schedule

To view a timer’s configuration, click the **View** icon next to the scheduled timer in the list.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/timer_events_schedule.png)
</Frame>

### 3. Activating and deactivating timers

Manage timer activation directly from the UI:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/activate_scheduled_processes.gif)
</Frame>

* **Activate:** Click the activate button in the Scheduled Processes tab.
* **Deactivate:** Click the same button to suspend the timer.

<Warning>
  You cannot edit timer configurations in the **Runtime** tab. To modify settings, update the process definition and redeploy.
</Warning>

***

## Use cases

<Steps>
  <Step title="Employee Onboarding reminder">
    A Timer Start Event can be scheduled to **automatically trigger** an onboarding process at a predefined time.

    **Example**: Process starts on **January 28, 2025, at 12:14 PM**, sending onboarding notifications.
  </Step>

  <Step title="Recurring Data processing jobs">
    A Cycle timer can execute a job **every 10 seconds for 60 repetitions**, ensuring periodic execution.
  </Step>

  <Step title="Scheduled Report generation">
    A cycle timer with a cron expression can generate a report at **1 AM every day**.
  </Step>
</Steps>

***

## Additional notes

* **Runtime Timer Control:**\
  Manage timers in the **Runtime** tab without changing the application build. Previously, timer activation was controlled by a checkbox in the **Start Timer node**, which is now read-only after deployment.

* **Timers in Multi-Swimlane Processes:**\
  Each swimlane can have its own timer. The **Scheduled Processes** tab displays each timer separately for clear management.

* **Exporting and Importing Builds:**\
  Timer activation settings are not editable during build export/import. All timer management occurs in the **Runtime** tab.


# UI Flow Sessions
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/ui-flow-sessions

Monitor and manage active UI Flow sessions, track session activity, and view audit logs. UI Flow Sessions provides visibility into user interactions with UI Flows, including session status, audit trails, and associated processes.

## Overview

**UI Flow Sessions** provides a comprehensive interface for monitoring and managing active user sessions with UI Flows. This feature enables you to track session activity, view audit logs, monitor associated processes, and debug UI Flow interactions in real-time.

<Card title="UI Flows" icon="file-pen">
  UI Flows are reusable, multi-platform user interfaces that work across web, iOS, and Android. They provide an alternative to BPMN processes when full process orchestration is not required.
</Card>

<Frame>
  ![UI Flow Sessions Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/uifs.png)
</Frame>

## Accessing UI flow sessions

Navigate to **Runtime Settings** → **UI Flow Sessions** from your project's Runtime view to access the sessions management interface.

<Info>
  You must have appropriate runtime permissions to view UI Flow Sessions. See [Workspace runtime editor](/5.9/setup-guides/access-management/workspaces-access-rights#workspace-runtime-editor) for details.
</Info>

## Sessions list

The **UI Flow Sessions** interface displays all active and historical sessions for UI Flows in your project. Each session appears as a row in the table with the following information:

| Column         | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| **ID**         | Unique session identifier (UUID format)                               |
| **UI Flow**    | The name of the UI Flow definition associated with this session       |
| **Status**     | Current session status (for example, `STARTED`, `FINISHED`, `ACTIVE`) |
| **Start Date** | Date and time when the session was initiated (localized format)       |

### Filtering and searching

Use the filter and search controls preceding the sessions table to find specific sessions:

* **Filter by definition**: Select a specific UI Flow definition from the dropdown to show only sessions for that UI Flow
* **Search by session id**: Enter a session ID (full or partial) to quickly locate a specific session

## Session details

Click on any session in the list to view detailed information about that session. The session details view provides comprehensive insights into session activity.

### Session information header

The session details header displays:

* **UI Flow**: The name of the UI Flow definition
* **UI Flow session ID**: The unique session identifier with a copy button for easy sharing
* **Status badge**: Visual indicator of the current session status (for example, `STARTED`, `FINISHED`)

### Detail tabs

The session details view includes four tabs for different aspects of the session:

<Tabs>
  <Tab title="Variables">
    Inspect runtime variables associated with the UI Flow session.

    The **Variables** tab displays the current state of all variables in the session. You can switch between two view modes using the dropdown:

    * **Tree View** — Expandable JSON tree viewer for navigating nested data structures
    * **JSON View** — Read-only Monaco code editor with JSON syntax highlighting

    Click **Export JSON** to download the session variables as a `.json` file.

    <Info>
      The Variables tab is the first tab in the session details panel, giving you immediate access to the session's data state when debugging.
    </Info>
  </Tab>

  <Tab title="Audit Log">
    View a chronological log of all events and actions that occurred during the session.

    **Audit Log columns:**

    | Column                 | Description                                                               |
    | ---------------------- | ------------------------------------------------------------------------- |
    | **Timestamp**          | Date and time when the event occurred (localized format)                  |
    | **User**               | User email or identifier who performed the action                         |
    | **Subject**            | Type of subject (e.g., "UI Flow Session")                                 |
    | **Event**              | Event type (e.g., "Start", "Navigate", "Action")                          |
    | **Subject Identifier** | Unique identifier for the subject (session ID, process instance ID, etc.) |
    | **Status**             | Event status (e.g., `success`, `failed`, `pending`)                       |
    | **View**               | Eye icon to view additional details about the event                       |

    <Frame>
      ![UI Flow Session Audit Log](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/uifs_audit_log.png)
    </Frame>

    **Common audit log events:**

    * **Start**: Session initialization
    * **Navigate**: Navigation between Navigation Areas
    * **Action**: Actions executed (e.g., Start Process, Navigate To)
    * **Process Start**: Process instances launched from the UI Flow
    * **Process Complete**: Process instances completed
  </Tab>

  <Tab title="Processes">
    View all process instances that were started from this UI Flow session.

    This tab shows:

    * Process instance IDs
    * Process definition names
    * Process status
    * Start and completion times
    * Links to process instance details

    <Info>
      Processes started from UI Flows using the **Start Process action** appear in this tab. This enables you to trace which business processes were triggered by user interactions in the UI Flow.
    </Info>
  </Tab>

  <Tab title="Workflows">
    View workflow execution details for workflows associated with this UI Flow session.

    This tab provides:

    * Workflow run IDs
    * Workflow execution status
    * Node-by-node execution timing
    * Input/output data
    * Execution logs

    <Card title="Workflow Debugging" icon="bug">
      Use the Workflows tab to debug workflow execution, view node execution times, and inspect data transformations. This is especially useful for troubleshooting AI agent workflows or data source operations.
    </Card>
  </Tab>
</Tabs>

## Session statuses

UI Flow sessions can have different statuses indicating their current state:

| Status       | Description                                                |
| ------------ | ---------------------------------------------------------- |
| **STARTED**  | Session has been initiated and is active                   |
| **ACTIVE**   | Session is currently active with ongoing user interactions |
| **FINISHED** | Session has been completed or closed                       |
| **FAILED**   | Session encountered an error and was terminated            |

<Info>
  Session statuses are updated in real-time as users interact with UI Flows. The status badge in the session details view reflects the current state.
</Info>

## Use cases

<CardGroup>
  <Card title="Session monitoring" icon="eye">
    Monitor active UI Flow sessions to understand user engagement and identify sessions that may need attention or support.
  </Card>

  <Card title="Audit and compliance" icon="shield-check">
    Track all user interactions and actions within UI Flow sessions for audit purposes and compliance requirements.
  </Card>

  <Card title="Debugging and troubleshooting" icon="bug">
    Investigate issues by reviewing audit logs, process instances, and workflow executions associated with a specific session.
  </Card>

  <Card title="Performance analysis" icon="chart-line">
    Analyze session duration, process start times, and workflow execution performance to identify optimization opportunities.
  </Card>

  <Card title="User support" icon="headset">
    Use session details to help users by understanding what actions they performed and identifying where they may have encountered issues.
  </Card>

  <Card title="Process tracking" icon="diagram-project">
    Trace which business processes were triggered from UI Flow interactions and monitor their execution status.
  </Card>
</CardGroup>

## Best practices

<CardGroup>
  <Card title="Regular monitoring" icon="clock">
    Regularly review active sessions to identify long-running sessions or sessions that may indicate user issues.
  </Card>

  <Card title="Use filters effectively" icon="filter">
    Use the filter by definition to focus on specific UI Flows when troubleshooting or analyzing usage patterns.
  </Card>

  <Card title="Review audit logs" icon="file-lines">
    Check audit logs for failed events or unexpected behavior patterns that may indicate configuration issues.
  </Card>

  <Card title="Track process launches" icon="play">
    Monitor the Processes tab to understand which business processes are most commonly triggered from UI Flows.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Session not appearing in list">
    **Possible causes:**

    * Session hasn't been started yet
    * Filter is excluding the session
    * User doesn't have permission to view sessions

    **Solutions:**

    * Verify the UI Flow is being accessed by users
    * Clear filters and search again
    * Check user permissions for Runtime access
    * Verify the build containing the UI Flow is active
  </Accordion>

  <Accordion title="Audit log shows failed events">
    **Possible causes:**

    * Event handler configuration error
    * Process start failure
    * Workflow execution error
    * Permission issues

    **Solutions:**

    * Review the event details using the view icon
    * Check process definition is published and accessible
    * Verify workflow configuration in Integration Designer
    * Confirm user has necessary permissions
    * Review browser console for client-side errors
  </Accordion>

  <Accordion title="Process instances not showing">
    **Possible causes:**

    * Process wasn't started from the UI Flow
    * Process start action failed
    * Process instance was deleted

    **Solutions:**

    * Verify the Start Process action is configured correctly
    * Check audit log for process start events
    * Confirm process definition is in the active build
    * Review Failed Process Start section for errors
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup>
  <Card title="UI Flows" href="/5.9/docs/building-blocks/ui-flows" icon="file-pen">
    Learn about UI Flows, their capabilities, and how to create and configure them.
  </Card>

  <Card title="Start Process action" href="/5.9/docs/building-blocks/ui-flows#configuring-the-start-process-action" icon="play">
    Understand how to configure Start Process actions to launch processes from UI Flows.
  </Card>

  <Card title="Process Instance" href="/5.9/docs/projects/runtime/active-process/process-instance" icon="diagram-project">
    Learn how to monitor and manage process instances that are started from UI Flows.
  </Card>

  <Card title="Chat Component" href="/5.9/ai-platform/chat-component" icon="comments">
    Understand how chat sessions are tracked within UI Flow Sessions for AI-powered workflows.
  </Card>
</CardGroup>


# Workspaces
Source: https://docs.flowx.ai/5.9/docs/projects/workspaces

Workspaces enable organizations to manage multiple business contexts within one FlowX instance while maintaining logical data isolation.

<Frame>
  ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
</Frame>

<Info>
  **Scope**: This page covers Designer-side access to workspaces and projects. For runtime authorization — how end users access published solutions on 5.9.x — see [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).
</Info>

### Key benefits

<CardGroup>
  <Card title="Faster Onboarding" icon="rocket">
    Onboard new business verticals in days instead of weeks with shared platform capabilities
  </Card>

  <Card title="Data Isolation" icon="shield-check">
    Provide secure separation between different business contexts while allowing controlled resource sharing
  </Card>

  <Card title="Enhanced Access Control" icon="key">
    Implement granular permissions with role-based access control (RBAC) and access control lists (ACLs)
  </Card>
</CardGroup>

## Key concepts

### Workspace

A workspace is a logical grouping of entities and assets defined in FlowX that are only available to a subset of users who are given explicit access. Each workspace operates independently, ensuring data and configuration separation between different business contexts.

### Multi-workspace user access

Users can be granted access to multiple workspaces and can switch between them as needed. When a user has access to multiple workspaces, they can select which workspace to enter after authentication.

### Data isolation

Workspaces provide logical data isolation, meaning that resources (projects, libraries, themes, etc.) are scoped to specific workspaces and cannot be accessed from other workspaces without explicit sharing configurations.

### Additional terminology

* **Group**: A collection of users who share common characteristics, responsibilities, or access needs within a system. Groups are used to simplify access control by managing permissions collectively rather than assigning them individually to each user.
* **Permissions**: Define what actions can be performed on resources. They are fine-grained access controls that specify privileges for a resource type, such as: read process, edit process, delete process.
* **Roles**: Collections of permissions grouped together based on job functions or responsibilities. They simplify permission management by assigning a set of permissions to users instead of managing them individually.

<Info>
  **Role assignment rule**: Roles are never assigned directly to users or groups. A user or group is assigned a role ONLY when given access to a workspace OR a project/library. **Exception**: `org_admin` role is the only one assigned to users directly at the organization level.
</Info>

<Note>
  When a user has multiple roles assigned in the context of a workspace or project, their access level is the union of all permissions from all roles associated with the user.
</Note>

## Workspace use cases

<AccordionGroup>
  <Accordion title="Multiple Business Lines" icon="building">
    **Isolation Level**: High

    Different use cases, projects, permissions, and users between business verticals (e.g., retail vs. corporate vs. investment banking).

    **Shared Resources**:

    * Shared users across business lines
    * Shared library builds
    * Shared themes (configurable)

    **Example**: A multinational bank with separate workspaces for Retail Banking, Corporate Banking, and Investment Banking, each with its own processes but sharing common user authentication and compliance libraries.
  </Accordion>

  <Accordion title="Regional Separation" icon="globe">
    **Isolation Level**: Medium

    Same business line across different regions, subject to local regulations.

    **Shared Resources**:

    * Libraries and common processes
    * Some shared users with multi-region access

    **Example**: An insurance company with workspaces for US, EU, and APAC operations, sharing global insurance processes but maintaining region-specific compliance and regulatory processes.
  </Accordion>

  <Accordion title="Distinct Organizations" icon="users">
    **Isolation Level**: Highest

    Complete separation for different customers or organizations.

    **Shared Resources**: None

    **Example**: A consulting firm providing FlowX services to multiple clients, with completely isolated workspaces for each client organization.
  </Accordion>
</AccordionGroup>

## How workspaces work

### Authentication and access flow

<Steps>
  <Step title="User Authentication">
    User logs in using OAuth 2.0 through the configured identity provider (Keycloak or client's existing provider). Authenticated users are saved with subject ID in FlowX database.
  </Step>

  <Step title="Permission Retrieval">
    System fetches the user's workspace permissions and available workspaces
  </Step>

  <Step title="Workspace Selection">
    If user has access to multiple workspaces, they select which workspace to enter
  </Step>

  <Step title="Context Loading">
    FlowX Designer loads with workspace-specific content, projects, and permissions
  </Step>
</Steps>

### Workspace selection experience

The workspace selection experience varies based on user access:

<Tabs>
  <Tab title="Single Workspace Access">
    **Direct Navigation**: Users with access to only one workspace are automatically redirected to the projects page within their workspace.

    **UI Behavior**: The workspace dropdown selector is disabled since no selection is needed.

    **Session Flow**: Simplified experience with no additional selection steps required.
  </Tab>

  <Tab title="Multiple Workspace Access">
    **Homepage Display**: Users see a "Your Workspaces" homepage after authentication.

    **Workspace Layout**:

    * Workspaces displayed in alphabetical order
    * 3 workspace tiles per row
    * Name truncation with "..." for long names
    * Hover tooltips show full workspace names

    **Navigation to Organization Admin view**: when a logged in user is an organization admin, Organization Settings button appears on Select Workspace page in top right corner.
  </Tab>

  <Tab title="No Workspace Access">
    **Empty State Display**: Users without access to any workspace see an informational message instead of the workspace list.

    **Message Content**: "You're not assigned to a workspace yet" or similar notification

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/no_workspace.png)
    </Frame>

    **Next Steps**: User must wait for an organization admin to grant workspace access before they can proceed

    <Note>
      This scenario commonly occurs for new users from LDAP/Active Directory after their first login, before an admin assigns workspace access.
    </Note>
  </Tab>
</Tabs>

#### Session management

<Info>
  **Session Persistence**: Workspace selection is saved for the user session. On subsequent visits within the same session, users are automatically redirected to their previously selected workspace.
</Info>

#### Error handling and access denied scenarios

<AccordionGroup>
  <Accordion title="No Access to Selected Workspace" icon="ban">
    **Trigger**: User attempts to access a workspace they don't have permissions for, or workspace ID is incorrect

    **System Response**: User is redirected to `workspace/403` error page

    **Common Causes**:

    * Workspace access was revoked
    * User navigated to an invalid workspace ID
    * Workspace was deleted or renamed

    **Resolution**: Contact workspace admin or organization admin to restore access
  </Accordion>

  <Accordion title="No Access to Resource" icon="lock">
    **Trigger**: User attempts to access a specific resource (project, library, etc.) they don't have permissions for

    **System Response**: User is redirected to `403` error page

    **Common Causes**:

    * Insufficient project-level permissions
    * Resource is restricted to specific roles or groups
    * Project access was revoked

    **Resolution**: Request access from the project owner or workspace admin
  </Accordion>
</AccordionGroup>

### Resource management

<Tabs>
  <Tab title="Project Isolation">
    **Workspace Scoping**: Each project is tagged with its workspace ID and only accessible within that workspace

    **Independent Lifecycle**: Projects in different workspaces can have the same names and follow independent versioning

    **Cross-Workspace Import**: The same project can now be imported into multiple workspaces on the same environment. Each imported project maintains its own independent lifecycle with separate active policies and access controls.

    **Import Behavior**: Projects created from version or build import are created with access only for the currently logged in user with 'Project Owner' role. Workspace admins are also able to view projects. Access can be extended to required users subsequently.

    **Runtime Permissions**: Permissions for Runtime section are received by users with workspace role. Users inherit runtime permissions from workspace role for ALL projects/libraries they have access to.
  </Tab>

  <Tab title="Library Sharing">
    **Build Sharing**: Library builds can be reused across workspaces on the same environment

    **Controlled Access**: Libraries from other workspaces can be added as dependencies if permissions allow

    **Version Management**: Single version constraint applies across workspace boundaries for shared libraries

    **Workspace Access**: All builds created in workspace for any library have 'public' access within workspace. When adding library dependencies, all libraries with builds are available as dependencies.

    **Cross-Workspace Sharing**: Library builds can be shared across workspaces using export/import mechanism

    <Warning>
      **Important**: Library builds from Workspace A can be imported into Workspace B on same environment. Libraries containing only builds are not viewable to workspace users outside the Dependencies page.
    </Warning>

    **Library Creation**: Libraries are created only with version import (not created when importing a build of a library).
  </Tab>

  <Tab title="Theme Management">
    **Workspace Themes**: Each workspace can have its own themes and branding

    **Shared Themes**: Themes can be shared between workspaces when configured appropriately

    **Brand Consistency**: Maintain consistent branding across business units or customize per workspace

    **Default Theme**: Default theme can be set in each workspace. When creating a project or library, the project/library version inherits the workspace default theme as the configured theme in Version settings.

    **Export/Import**: Themes can be shared across workspaces using export/import.
  </Tab>

  <Tab title="Media Files & Fonts">
    **Media Files**: Each workspace can create and manage workspace specific media files, not accessible to be used by other workspaces. However, when exporting themes, media files will also be exported and can be imported easily in other workspace together with the theme.

    **Fonts**: Fonts can be uploaded only in Organization Settings section, and all uploaded fonts will be shared by all workspaces.
  </Tab>
</Tabs>

### Additional workspace features

#### Command Center (AI Agents)

<Info>
  AI Agents permission is a project-level permission. **Consequence**: Command center is available only on projects or libraries pages.
</Info>

#### Audit Logs

Audit log entry in main menu for every workspace will be available only for users with Workspace Admin role. The reason for this is that global audit log includes all logs for all projects/libraries in workspace.

## Access control

### Role-based access control (RBAC)

<Info>
  For detailed role permissions and setup instructions, see [Workspaces Access Rights](../../setup-guides/access-management/workspaces-access-rights).
</Info>

<CardGroup>
  <Card title="Predefined Roles" icon="user-tag">
    * **Project editor** - Can modify project content, processes, and configurations. Includes all Project Viewer permissions.
    * **Project viewer** - Read-only access to project content and processes. Cannot make modifications.
    * **Workspace user** - View only access to workspace entities. Can create projects, but only sees projects they have explicit access to.
    * **Owner** - Automatically assigned to project creators. Full control over project settings, access management, and can delete the project.
    * **Theme editor** - Extends workspace user role to include permissions to manage themes and associated resources (global media files).
    * **Workspace admin** - Manages all workspace level resources including users, roles, themes. Can configure access and content, but cannot manage organization-wide settings.
    * **Runtime editor** - Enables users to test runtime functionality and manage runtime policies without full configurator permissions. Commonly used by QA teams and testers who need to manage "change active policy" operations and test processes during runtime without broader editing capabilities.
  </Card>

  <Card title="Workspace-Specific" icon="building">
    Roles are specific to each workspace - a user can have different roles in different workspaces
  </Card>
</CardGroup>

<Note>
  Only pre-defined roles are available for workspace and project/library access.
</Note>

#### Detailed role permissions

To add a user to a workspace, and to assign a role to the user, you need to go to **Organization settings** page and select your desired workspace, then add the user to the workspace and assign the role to the user.

* **Workspace admin**: Manages all workspace level resources including users, roles, themes. Can configure access and content, but cannot manage organization-wide settings.

<Warning>
  Workspace admins will be able to view and edit ALL projects and libraries in workspace, regardless of project/library access settings.
</Warning>

* **Workspace user**: View only access to workspace entities. Can create projects, but only sees projects they have explicit access to.

* **Theme editor**: Extends workspace user role to include permissions to manage themes and associated resources (global media files).

* **Runtime editor**: Enables users to test runtime functionality and manage runtime policies without full configurator permissions. Commonly used by QA teams and testers who need to manage "change active policy" operations and test processes during runtime without broader editing capabilities.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wks1.png)
</Frame>

### User groups

<Info>
  User groups simplify permission management by allowing you to assign permissions to groups rather than individual users.
</Info>

* **Default Groups**: Each workspace includes an "Everyone in workspace" default group
* **Custom Groups**: Create groups based on teams, departments, or project requirements
* **Inherited Permissions**: Users automatically inherit permissions from their group memberships

### Access control lists (ACLs)

<AccordionGroup>
  <Accordion title="Resource-Specific Permissions" icon="file-shield">
    Grant fine-grained control over individual resources within a workspace, allowing exceptions to general role permissions.

    **Example**: A user with `project_viewer` role can be granted edit access to a specific project without becoming a full `configurator`.
  </Accordion>

  <Accordion title="Exception-Based Access" icon="user-check">
    Provide specific users or groups access to individual resources without requiring full platform permissions.

    **Use Case**: External consultants can be given access to specific projects they're working on without broader workspace access.
  </Accordion>

  <Accordion title="Owner Management" icon="crown">
    Resource creators can manage access to their specific resources without requiring full admin intervention.

    **Benefit**: Project owners can add team members to their projects without needing admin approval for each addition.
  </Accordion>
</AccordionGroup>

### Project-level access control

Projects and libraries support fine-grained access control through dedicated project roles that work alongside workspace-level permissions.

<CardGroup>
  <Card title="Project Owner" icon="crown">
    Automatically assigned to project creators. Full control over project settings, access management, and can delete the project.
  </Card>

  <Card title="Project Editor" icon="pen-to-square">
    Can modify project content, processes, and configurations. Includes all Project Viewer permissions.
  </Card>

  <Card title="Project Viewer" icon="eye">
    Read-only access to project content and processes. Cannot make modifications.
  </Card>
</CardGroup>

#### Creating a project

<Steps>
  <Step title="Create Project">
    Create a new project by clicking the **+** icon in the top-right corner of the Projects page.
  </Step>

  <Step title="Owner Assignment">
    The currently logged-in user is automatically assigned as Project Owner with full access rights.
  </Step>

  <Step title="Extend Access">
    Project owners can subsequently add users or groups with Project Editor or Project Viewer roles as needed.
  </Step>
</Steps>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wks2.png)
</Frame>

#### Access management inheritance

* **Project Editor role** automatically includes Project Viewer permissions
* **Multiple roles**: Users can have both workspace-level and project-level roles simultaneously
* **Permission union**: When users have multiple roles, their access is the combination of all permissions from all assigned roles

## Organization administration

### Organization admin role

<Info>
  The `org_admin` role is the only role assigned directly to users at the organization level, not workspace level.
</Info>

Organization admins will be able to see all workspaces and have the same permissions as Workspace Admins inside each workspace. Multiple users can have this role assigned. Role can be assigned/revoked by other org admins.

### User management

<Warning>
  Users are created in FlowX only after their first login in FlowX Designer.
</Warning>

The **Organization Users** page lists only **Designer users** — users who have logged into FlowX Designer at least once, or who were manually created by an organization admin. It does not list **Runtime users** (Keycloak roles/groups used for process-level permissions at runtime). Designer users and Runtime users are managed separately:

* **Designer users** — managed in **Organization Settings → Users**. Control access to the FlowX Designer, workspaces, projects, and libraries.
* **Runtime users** — managed in **Organization Settings → Runtime Roles** and **Runtime Groups**. Control access to process instances at runtime (e.g., who can start or view a process).

<Info>
  End-user groups are managed inside FlowX (not in Keycloak), and a role grants access only on the solutions where it's been explicitly shared from the Solutions page. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).
</Info>

The **User Details** page shows the Designer user's Workspace access summary (which workspaces they belong to and what roles they hold).

#### User creation scenarios

<Tabs>
  <Tab title="LDAP/Active Directory Users">
    **Sync Behavior**: Users from customer's LDAP/Active Directory are not automatically created in FlowX.

    **Onboarding Steps**:

    1. User logs into FlowX Designer for the first time
    2. They are redirected to a "You're not assigned to a workspace yet" message page
    3. User account is now created in FlowX and appears in the Users list in Organization Settings
    4. Organization admin assigns workspace access with appropriate role (Workspace User, Workspace Admin, Theme Editor, or Runtime Editor)
    5. On next login, user will have access to assigned workspaces

    <Note>
      Users synced from LDAP will only appear in FlowX after their first login attempt.
    </Note>
  </Tab>

  <Tab title="Direct FlowX Creation">
    **Prerequisites**: Only available when using Keycloak as the authentication provider.

    **Creation Process**:

    1. Organization admin clicks the + icon in Users section
    2. Enter user details (name, email, password, runtime roles)
    3. User is immediately created in both Keycloak and FlowX Designer
    4. Organization admin can immediately assign workspace access
    5. User can log in directly without the initial "no workspace" flow

    <Note>
      This method is primarily for internal use and may not be available in all deployments. If direct user creation is needed, users should be created directly in Keycloak.
    </Note>
  </Tab>
</Tabs>

### Additional organization settings

#### Runtime roles and groups

Legacy Roles and Groups pages (for managing roles and groups only in Keycloak) are accessible in Organization Settings section and renamed **Runtime Roles** and **Runtime Groups**.

Will be used going forward to manage any roles needed for process permission configuration.

<Info>
  End-user groups are managed in FlowX rather than Keycloak. Role assignment to a user or group is set per-solution from the Share modal on the Solutions page. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).
</Info>

<Info>
  All workspaces will share the same list of runtime roles and groups.
</Info>

<Warning>
  Runtime Roles and Runtime Groups require Keycloak as the IAM backend. External identity providers (Azure AD, Okta, etc.) federate into Keycloak — they don't replace it. See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for setup.
</Warning>

#### Set environment info

Configuring client and environment information is available only in Organization settings section under Platform status page.

## Workspace management

### Creating and managing workspaces

<Steps>
  <Step title="Admin Access Required">
    Only users with organization administrator permissions can create new workspaces
  </Step>

  <Step title="Workspace Configuration">
    Set workspace name, description, and basic settings during creation
  </Step>

  <Step title="User Assignment">
    Add initial users and assign appropriate roles to get started

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wks3.png)
    </Frame>
  </Step>
</Steps>

<Warning>
  Deleting a workspace is not currently available.
</Warning>

### Workspace environment type

Workspaces are labeled with an **Environment Type** that indicates their purpose within your deployment. The label is visible in every workspace listing, so users can immediately tell whether they are working in development, testing, or live data — particularly important when the same project (by UUID) is imported into more than one workspace via [cross-workspace project import](#cross-workspace-project-import).

### Available types

| Type           | When to use                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| **Sandbox**    | Development, experimentation, and testing. The default for any workspace on a non-production FlowX environment. |
| **Staging**    | Pre-production validation and QA — the workspace that mirrors production data shape but is not customer-facing. |
| **Production** | Live, end-user-facing deployment. Reserve this label for workspaces that drive real customer traffic.           |

### Setting the type

The Environment Type is set at workspace creation and can be changed later by a Workspace or Organization Admin:

* **At creation:** the **Create Workspace** dialog includes an **Environment Type** dropdown. Pick the type that matches the workspace's intended use.
* **After creation:** go to **Organization Settings** → select your workspace → adjust the **Environment Type** dropdown.

<Info>
  The selected type is displayed as a **Type** column in the Designer workspace list, so administrators and users can identify the environment without opening workspace settings.
</Info>

### Multi-workspace identification

Because the same FlowX environment can host multiple workspaces, and the same project (same UUID) can be imported into more than one workspace, the Environment Type label is the primary cue for *where* a user is working. Without it, a designer opening a project cannot tell at a glance whether they are about to edit a Sandbox copy or the Production copy of the same project.

Recommended patterns:

* On a **non-production FlowX environment**, label every workspace **Sandbox** — the environment itself is not customer-facing, regardless of how the workspaces are organized internally.
* On a **production FlowX environment** that hosts multiple workspaces (for example, UAT, Staging, and Production for the same project), use **Staging** for the validation workspace and **Production** for the live workspace. The Environment Type lets users distinguish them inside the same Designer.
* Avoid mixing labels arbitrarily across an environment — the value of the cue depends on the label matching the workspace's role.

<Tip>
  Pair Environment Type with a clear **workspace naming convention** (for example, `retail-prod`, `retail-staging`, `retail-sandbox`). The combination of name and type makes the destination of every action — sharing, importing, deploying — unambiguous.
</Tip>

### User management within workspaces

<Tabs>
  <Tab title="Adding Users">
    * **Direct Assignment**: Add users directly to workspace with specific roles
    * **Group Membership**: Add users to groups that inherit workspace permissions
    * **Multi-Workspace Access**: Users can be members of multiple workspaces
  </Tab>

  <Tab title="Role Assignment">
    * **Multiple Roles**: Users can have multiple roles within a workspace
    * **Role Inheritance**: Roles can inherit permissions from other roles
    * **Workspace Scoping**: User roles are specific to each workspace
  </Tab>

  <Tab title="Access Matrix">
    * **Visual Interface**: See all users, groups, and their permissions at a glance
    * **Quick Adjustments**: Easily modify permissions and access levels
    * **Audit Capabilities**: Track who has access to what resources
  </Tab>
</Tabs>

## Migration and compatibility

### Initial setup requirements

<Warning>
  **Critical Setup Step**: Before starting any FlowX environment, the initial organization admin must be configured.
</Warning>

<Note>
  Complete setup instructions are available in the [Workspaces Setup Guide](../../setup-guides/authorization-setup-guide).
</Note>

1. To create the first user in FlowX Designer with organization admin role, an environment variable `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME` needs to be configured with the username of the user from Identity Store (Keycloak/ other Identity Store from where the users are used to login in FlowX.AI).
2. If request to Keycloak fails, the fallback is to use `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID` to create the organization admin user. Value that must be set is the ***subject identifier***. (***sub*** in *JWT token OR* user’s id in Keycloak).

<Info>
  This step is important for creating any environment, no matter if there's a pre-existing env or a newly created one.
</Info>

<Warning>
  **IMPORTANT**: Instruct DeevOps team to set this user id **BEFORE** system startup. Otherwise the authorization-service startup will fail. Ensure the correct value is set. The correct value is the subject id of the user, value that will be populated by the authorization service in the access token used for FlowX login.
</Warning>

<AccordionGroup>
  <Accordion title="For existing FlowX customers" icon="building">
    <Warning>
      When upgrading from an earlier FlowX LTS, a default workspace is automatically created containing all your existing resources.
    </Warning>

    **What Happens During Migration:**

    * All existing projects, libraries, and themes are moved to a default workspace
    * All existing functionality continues to work without changes

    **Default workspace details:**

    * Name: **"Default workspace"** (can be changed following the migration)
    * UUID: **"00000000-0000-0000-0000-000000000001"**

    **What gets migrated:**

    * All active process instances will be migrated under default workspace
    * Failed process start instances migration
    * Workflow instances migration
    * Scheduled processes migration
    * Audit logs migration

    <Note>
      Out of office and Fonts will not be migrated under default workspace, as they are managed at organization level.
    </Note>

    <Warning>
      For clients who need inactive process instances migrated, we'll provide migration script which will be run post migration.
    </Warning>

    **Post-migration manual steps:**

    <Warning>
      **Important**: Existing users will not be migrated; they will need to log into FlowX so that their user is created.
    </Warning>

    * Organization admin will need to provide individual access to workspace for each user
    * Access to projects and libraries should be additionally configured as per workspace requirements
    * Existing admin roles and groups used for FlowX Designer access are deprecated and should be **removed** post-migration from Keycloak

    <Note>
      Step is optional, but encouraged so that the role list for runtime permissions is manageable. List of deprecated roles (which can be removed) will be provided in documentation.
    </Note>
  </Accordion>

  <Accordion title="For new FlowX 5.x installations" icon="building">
    **Initial Setup Process:**

    1. Configure the first workspace administrator user
    2. Create the initial workspace
    3. Set up users and role assignments
    4. Begin creating projects and processes
  </Accordion>
</AccordionGroup>

## Best practices

### Workspace design

<CardGroup>
  <Card title="Clear Boundaries" icon="compass">
    Define workspaces based on clear business, regulatory, or organizational boundaries
  </Card>

  <Card title="Naming Conventions" icon="tag">
    Use consistent naming conventions for workspaces, roles, and resources
  </Card>

  <Card title="Documentation" icon="text">
    Document workspace purposes, user access patterns, and governance policies
  </Card>

  <Card title="Scalability Planning" icon="chart-line-up">
    Plan workspace structure to accommodate future growth and organizational changes
  </Card>
</CardGroup>

### Permission management

* **Principle of Least Privilege**: Grant minimum necessary permissions
* **Group-Based Management**: Use groups for permission management rather than individual assignments
* **Regular Audits**: Periodically review and audit workspace permissions
* **Clear Ownership**: Establish clear ownership models for workspace resources

### Resource sharing

* **Controlled Sharing**: Implement clear policies for resource sharing between workspaces
* **Dependency Management**: Track and manage dependencies between shared resources
* **Version Control**: Maintain version control for shared libraries and themes

## Common use cases

<AccordionGroup>
  <Accordion title="Banking - Multi-Division Operations" icon="building-columns">
    **Scenario**: Large bank with retail, corporate, and investment banking divisions

    **Workspace Structure**:

    * Retail Banking Workspace
    * Corporate Banking Workspace
    * Investment Banking Workspace
    * Shared Compliance Workspace (for common libraries)

    **Benefits**: Division autonomy while sharing compliance processes and user management
  </Accordion>

  <Accordion title="Insurance - Geographic Separation" icon="globe">
    **Scenario**: Insurance company operating in multiple countries

    **Workspace Structure**:

    * US Operations Workspace
    * EU Operations Workspace
    * APAC Operations Workspace

    **Benefits**: Region-specific regulatory compliance while sharing global insurance processes
  </Accordion>
</AccordionGroup>

## Cross-workspace project import

You can import the same project into multiple workspaces on the same environment. This feature enables organizations to use workspaces to represent different operational environments (such as UAT, staging, pre-production) on a single FlowX deployment, reducing operational costs.

### How it works

<CardGroup>
  <Card title="Import to Multiple Workspaces" icon="copy">
    Import a project build (and optionally a version) into different workspaces on the same environment
  </Card>

  <Card title="Independent Lifecycle" icon="arrows-spin">
    Each imported project maintains its own lifecycle with separate active policies and access controls
  </Card>

  <Card title="No Impact on Original" icon="shield-check">
    Importing to another workspace does not affect the original project's settings, policies, or process instances
  </Card>

  <Card title="Separate Process Instances" icon="layer-group">
    Process instances are workspace-specific; imported projects have no instances initially until processes run in the new workspace
  </Card>
</CardGroup>

### Import behavior

| Aspect            | Behavior                                                                                                              |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Active Policy** | The imported build is automatically set as the active policy in the new workspace                                     |
| **User Access**   | Workspace users must be granted appropriate rights on the imported project (e.g., project viewer) to interact with it |
| **Database**      | Projects across workspaces on the same environment share the same database                                            |
| **Configuration** | All project configuration lives within each specific workspace independently                                          |

<Tip>
  **Use case**: Organizations like banks and insurance companies can use this feature to represent different upper environments (UAT, Staging, Production) as separate workspaces on the same FlowX deployment, significantly reducing infrastructure and DevOps costs.
</Tip>

***

## Limitations and considerations

### Current limitations

* **Resource Isolation**: Direct access to resources from other workspaces is not possible
* **Single Environment Sharing**: Library sharing only works within the same FlowX environment
* **Permission Inheritance**: Workspace permissions don't automatically inherit across workspace boundaries

### Additional limitations

<Warning>
  * Workspace import/export is out of scope; each FlowX environment has its own default workspace and workspaces are managed independently on each instance.
  * Library builds from other workspaces are only visible on the Dependencies page after import, not as full library entries in the workspace.
</Warning>

### Planning considerations

* **Change Management**: Organizational alignment needed for governance models
* **User Training**: Users need to understand workspace selection and navigation
* **Governance Policies**: Clear policies needed for resource sharing and access management
* **Migration Planning**: Existing customers should plan workspace structure before creating additional workspaces

***

## Related documentation

* [Workspaces Setup Guide](../../setup-guides/authorization-setup-guide)
* [Workspaces Access Rights](../../setup-guides/access-management/workspaces-access-rights)


# Get Build Info
Source: https://docs.flowx.ai/5.9/docs/api/start-process/get-build-info

GET https://admin.devmain.flowxai.dev/rtm/api/runtime/wks/{workspaceId}/app/{appId}/build/info
Retrieve the active build for an app and workspace. Returns the buildId you need to start a process via REST.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

## Base URL

* Always prepend the endpoint with the correct Base URL.
* For different environments (like staging or production), switch the base URL accordingly.

<Info>
  This endpoint is only accessible via the admin environment. Ensure that you are using the correct admin base URL when making requests.
</Info>

## Authorization

<ParamField type="string" placeholder="Bearer <token>">
  Bearer authentication header of the form Bearer `<token>`, where `<token>` is your auth token.
</ParamField>

## Request headers

<ParamField type="string">
  Bearer token required for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField type="string" placeholder="application/json, text/plain, */*">
  Specifies the media types that are acceptable for the response. Defaults to accepting JSON and plain text responses.
</ParamField>

<ParamField type="string" placeholder="gzip, deflate, br, zstd">
  Indicates supported content encoding algorithms for the response.
</ParamField>

<ParamField type="string" placeholder="en-GB,en-US;q=0.9,en;q=0.8">
  Specifies language preferences for the response.
</ParamField>

## Path Parameters

<Info>
  **Need help finding the Application ID or Workspace ID?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for detailed instructions on where to locate these values in FlowX Designer.
</Info>

<ParamField type="string" placeholder="12345678-1234-1234-1234-123456789012">
  The unique identifier of the workspace that contains the application. This parameter is used to search for the appId within the specified workspace. This value is populated by the Configurator in the container app and varies across different environments (e.g., production, development, UAT).
</ParamField>

<ParamField type="string" placeholder="dbe0ab87-539b-4015-962d-6e73226b9e58">
  The unique identifier of the application whose build information is being retrieved.
</ParamField>

<RequestExample>
  ```bash theme={"system"}
  curl --request GET \
    --url https://admin.devmain.flowxai.dev/rtm/api/runtime/wks/{workspaceId}/app/{appId}/build/info \
    --header "Authorization: Bearer <token>" \
    --header "Flowx-Platform: web"
  ```
</RequestExample>

## Response Fields

<ResponseField name="workspaceId" type="string">
  The unique identifier of the workspace that contains the application.
</ResponseField>

<ResponseField name="buildId" type="string">
  The unique identifier of the build entity.
</ResponseField>

<ResponseField name="applicationId" type="string">
  The ID of the application associated with the build.
</ResponseField>

<ResponseField name="buildSettings" type="object">
  Contains configuration settings related to the build.

  <Expandable title="Properties">
    <ResponseField name="applicationVersionId" type="string">
      The version ID of the application associated with the build.
    </ResponseField>

    <ResponseField name="platforms" type="string">
      Indicates the supported platforms for the build (e.g., `OMNICHANNEL`).
    </ResponseField>

    <ResponseField name="themeId" type="string">
      The ID of the theme applied to the build.
    </ResponseField>

    <ResponseField name="dateDisplayFormat" type="object">
      Defines the format used for displaying dates.

      <Expandable title="Properties">
        <ResponseField name="format" type="string">
          Specifies the date format style (e.g., `short`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="numberDisplayFormat" type="object">
      Configuration for displaying numerical values, including decimal precision.

      <Expandable title="Properties">
        <ResponseField name="minDecimals" type="integer">
          The minimum number of decimal places to display in numerical values.
        </ResponseField>

        <ResponseField name="maxDecimals" type="integer">
          The maximum number of decimal places to display in numerical values.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="currencyDisplayFormat" type="object">
      Defines the format used for displaying currency.

      <Expandable title="Properties">
        <ResponseField name="format" type="string">
          Specifies the format for displaying currency (e.g., `isoCode`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="defaultLanguageCode" type="string">
      The default language code for the build (e.g., `en` for English).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Success theme={"system"}
  {
    "workspaceId": "12341234-1234-1234-1234123412341234",
    "buildId": "11111111-1111-1111-1111-111111111111",
    "applicationId": "4ffeeb22-e84a-400f-9e07-b305ab0b4241",
    "buildSettings": {
      "applicationVersionId": "99f24e3f-e331-48ad-a503-2cc1cee5fb95",
      "platforms": "OMNICHANNEL",
      "themeId": "12345678-1234-1234-1234-123456789012",
      "dateDisplayFormat": {
        "format": "short"
      },
      "numberDisplayFormat": {
        "minDecimals": 1,
        "maxDecimals": 2
      },
      "currencyDisplayFormat": {
        "format": "isoCode"
      },
      "defaultLanguageCode": "en"
    }
  }
  ```
</ResponseExample>

## Response Headers

<ResponseField name="Access-Control-Allow-Credentials" type="boolean">
  Indicates whether the response can be exposed when credentials are present. Example: `true`.
</ResponseField>

<ResponseField name="Access-Control-Allow-Headers" type="string">
  Lists the allowed headers in the actual request.
</ResponseField>

<ResponseField name="Access-Control-Allow-Methods" type="string">
  Specifies the allowed HTTP methods.
</ResponseField>

<ResponseField name="Access-Control-Allow-Origin" type="string">
  Indicates the allowed origin for cross-origin requests.
</ResponseField>

<ResponseField name="Content-Encoding" type="string">
  Specifies the encoding used to compress the response.
</ResponseField>

<ResponseField name="Content-Type" type="string">
  Indicates the media type of the response content.
</ResponseField>

<ResponseField name="Strict-Transport-Security" type="string">
  Enforces secure (HTTPS) connections to the server.
</ResponseField>

<ResponseField name="Vary" type="string">
  Specifies that the response may vary based on the `Accept-Encoding` request header.
</ResponseField>

<ResponseField name="X-Content-Type-Options" type="string">
  Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`.
</ResponseField>

<ResponseField name="X-XSS-Protection" type="string">
  Controls the cross-site scripting (XSS) filter. Example: `0` (disabled).
</ResponseField>


# Project data model
Source: https://docs.flowx.ai/5.9/docs/building-blocks/project-data-model

Define reusable data types at the project level to ensure consistency across processes

## What is a project data model?

<Frame>
  ![Project Data Model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
</Frame>

The Project Data Model (PDM) lets you define reusable data types at the project level. These data types propagate to the process data models, ensuring data consistency across your FlowX.AI applications, including in Reusable Functions, Persistence Layer schemas, and other components.

With PDM, you create a centralized data structure that serves as the foundation for all processes within your project. This ensures that core data types like Customer, Product, or Document maintain consistent definitions throughout your application.

<Frame>
  ![Project Data Model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_process.png)
</Frame>

## Key concepts

<Tabs>
  <Tab title="Data Model Types">
    FlowX.AI supports several data model layers, each serving different purposes:

    | Data Model Layer         | Description                                                                                                   |
    | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
    | Process Data Model       | Can use data types defined in the Project Data Model or Library Data Model.                                   |
    | Project Data Model (PDM) | Defines data types that can be reused across processes and other resources within the project                 |
    | Library Data Model       | Defined within a library. Allows data types to be reused across multiple projects, promoting standardization. |

    <Frame>
      ![Data Model Types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_process.png)
    </Frame>
  </Tab>

  <Tab title="Data Types & Attributes">
    A **data type** defines the structure of a particular set of data. For example, a `Customer` data type might contain attributes like `name`, `email`, and `address`.

    An **attribute** is an individual property of a data type that specifies its data structure.

    Data types and attributes can be categorized based on their usage:

    * **Used/Unused**: A data type or attribute is considered "used" when it's incorporated into the structure of another data type.
    * **Referenced/Unreferenced**: Refers to data types or attributes from the Project Data Model being used within a Process Data Model or a UI Template.

    <Frame>
      ![PDM usage](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_usage.gif)
    </Frame>
  </Tab>
</Tabs>

## Benefits of project data model

<CardGroup>
  <Card title="Consistency" icon="check-double">
    Ensures data structure consistency across multiple processes and resources
  </Card>

  <Card title="Reusability" icon="recycle">
    Define once, use many times across processes, business rules, and other components
  </Card>

  <Card title="Efficiency" icon="bolt">
    Reduces development time by eliminating duplicate definitions
  </Card>

  <Card title="Maintainability" icon="wrench">
    Centralized management of data structures
  </Card>

  <Card title="Standardization" icon="ruler">
    Promotes the use of common data structures across projects
  </Card>
</CardGroup>

## How to use the project data model

### Access the project data model

<Steps>
  <Step title="Open FlowX.AI Designer">
    Open FlowX.AI Designer.
  </Step>

  <Step title="Navigate to your project">
    Select the project where you want to configure the Project Data Model.
  </Step>

  <Step title="Select Data Model">
    Select "Project Data Model" from the project menu.

    <Frame>
      ![Project Data Model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/where_to_find_pdm.png)
    </Frame>
  </Step>
</Steps>

### Define a project data model

<Steps>
  <Step title="Add a new data type">
    In the Project Data Model view, click **+** to add a new data type. A confirmation toast notifies you when the data type is created.

    <Frame>
      ![Add data type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_new_data_type.png)
    </Frame>
  </Step>

  <Step title="Name the data type">
    Provide a name for the data type.
  </Step>

  <Step title="Add attributes">
    Each data type displays an **Add attribute** button for creating the first attribute. After the first attribute exists, the button appears only on hover over the data type.

    When you select an attribute, a **settings side panel** opens on the right where you can configure:

    * Attribute name and type (string, number, boolean, object, array, enum)
    * Validations, sensitive data, and reporting settings
    * Example values for data mapping

    <Frame>
      ![Add attributes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_attributes.png)
    </Frame>
  </Step>
</Steps>

### Manage data types

#### Add a data type

1. Click **+** in the Data Types panel.
2. Enter the name and properties of the data type.
3. Use the inline **Add attribute** button on the data type to add attributes.
4. Save changes.

### Edit a data type

<Steps>
  <Step title="Select the data type">
    Select the data type in the Project Data Model.
  </Step>

  <Step title="Select an attribute">
    Click an attribute to open the **settings side panel** on the right with all configuration options.
  </Step>

  <Step title="Edit the attribute">
    Edit the attribute settings as needed. Changes are saved automatically.
  </Step>
</Steps>

### Attribute path

Each attribute displays a **path button** next to its name. Click it to view the full key path and copy it to your clipboard. This is useful when referencing keys in business rules, UI component bindings, or integration mappings.

<Info>
  Changes to data types propagate to all processes referencing them. If a process is using this data type, it will automatically get the updated structure.

  <Warning>
    However, changes do NOT propagate to UI Designer paths, which will need to be adjusted manually.
  </Warning>

  <video />
</Info>

### Remove a data type

<Steps>
  <Step title="Select the data type">
    Select the data type to remove.

    <Info>
      You can either delete an entire object or just a single attribute.
    </Info>

    <Frame>
      ![Delete data type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/remove_dm_obj.png)
    </Frame>
  </Step>

  <Step title="Click remove">
    Click the remove button.
  </Step>

  <Step title="Confirm deletion">
    You can delete the data type even if it's in use. The system will show you a warning message indicating which processes reference the data type.
  </Step>
</Steps>

<Warning>
  If the data type is in use by processes, you will receive a warning message showing which processes reference it. You can still proceed with the deletion, but this may affect the referenced processes.

  ![Delete data type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_delete.png)
</Warning>

### Working with referenced data types

When a data type from the Project Data Model is used in a Process Data Model:

1. The Process Data Model will display the referenced data type.
2. The referenced data type cannot be modified at the process level.
3. Changes to the data type in the Project Data Model will propagate to all referencing processes.

## Common scenarios

<Tabs>
  <Tab title="Edit a Key">
    <Steps>
      <Step title="Access PDM">
        Navigate to the Project Data Model.
      </Step>

      <Step title="Make changes">
        Make changes to an existing key or attribute.
      </Step>

      <Step title="Propagation">
        The changes automatically propagate to all processes using that key.
      </Step>

      <Step title="Updates">
        Referenced components in processes will be updated to reflect the changes, but UI Designer paths require manual adjustment.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Remove a Key">
    <Steps>
      <Step title="Access PDM">
        Navigate to the Project Data Model.
      </Step>

      <Step title="Remove key">
        Attempt to remove a key or object.
      </Step>

      <Step title="System check">
        System checks if the key is in use by any process.
      </Step>

      <Step title="Result">
        A warning modal shows references but allows deletion.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Change Type">
    <Steps>
      <Step title="Access PDM">
        Navigate to the Project Data Model.
      </Step>

      <Step title="Change type">
        Change the type of an attribute (e.g., from string to boolean).
      </Step>

      <Step title="Confirmation">
        System will prompt for confirmation as this might break processes.
      </Step>

      <Step title="Result">
        **Incompatible change**: References will be broken and removed from UI templates.

        **Compatible change**: No changes to references are required.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Use the Project Data Model in processes

1. Navigate to a process within your project.
2. Open the Process Data Model.
3. Project data types are available for selection.
4. Select the desired project data type to use in your process.
5. The data type is added to your Process Data Model, maintaining reference to the Project Data Model.

### Work with libraries

<Frame>
  ![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/library_pdm.png)
</Frame>

#### Integrate Library Data Models

1. Navigate to your project dependencies.
2. Add a library as a dependency. The library must have a build created.

<Frame>
  ![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/lib_pdm_dependency.png)
</Frame>

3. Library data types become available in your Project Data Model.

<Warning>
  Library data types are not visible by default! You must select the library source in the filter to display them.
</Warning>

<Tip>
  To filter by library types you can use the "Filter by source" feature.

  <Frame>
    ![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_lib_filter.png)
  </Frame>
</Tip>

4. You can now use the library data types in your data model.

<Frame>
  ![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/lib_pdm_flow.gif)
</Frame>

#### Handle duplicate types from libraries

When multiple libraries contain data types with the same name:

1. Both types will be visible in the Project Data Model with visual indicators.
2. Namespacing functionality will prevent technical issues.

<Frame>
  ![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/lib_multiple.png)
</Frame>

## Configure reporting and sensitive data settings

You can configure reporting and sensitive data settings directly from the attribute settings side panel:

1. Go to the Project Data Model.
2. Select an attribute to open the **settings side panel**.
3. Toggle **Sensitive data** or **Use in Reporting** as needed.

<Frame>
  ![Reporting Sensitive](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_reporting_sensitive.png)
</Frame>

<Note>
  These settings apply to all instances of the attribute across processes.
</Note>

<Tip>
  You can also access these settings from the three-dots menu in the upper right corner of the side panel → **Show details**.
</Tip>

## Project Data Model after version commitment

After committing a project version:

1. The Project Data Model becomes read-only.
2. You can still view the diagram and monitor usage.
3. This read-only configuration is available for any configuration on committed versions and applies also to resource data models.

<Frame>
  ![PDM after version commitment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_read_only.png)
</Frame>

3. To make changes to the data model, you will require a new project version.

<Frame>
  ![PDM after version commitment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_new_version.png)
</Frame>

## Search and filter

The Project Data Model interface provides tools to help you find and work with your data types:

1. Navigate to the Project Data Model.
2. By default, only project-level types are displayed.
3. Use filters to view library types as well.
4. Use the search function to find specific types by name.

## Update library dependencies

When updating library dependencies:

1. Navigate to the dependencies section.
2. Select the new library version.
3. The system will inform you of any breaking changes to data types.
4. You can decide whether to proceed with the update.
5. If you proceed, changes will propagate to processes according to compatibility rules.

## Real-world example: Insurance claims processing

<Info>
  This example demonstrates how an insurance company uses project data model for their claims processing system.
</Info>

<Accordion title="Core data types in PDM">
  The insurance company created these data types in their Project Data Model:

  <Frame>
    ![Insurance PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example2.png)
  </Frame>

  1. **Customer**
     * `customerId`: string
     * `firstName`: string
     * `lastName`: string
     * `dateOfBirth`: date
     * `contactInformation`: ContactInfo (reference)
     * `policyNumbers`: array of string
     * `customerSince`: date
     * `riskProfile`: RiskProfile (reference)
     * *Settings*: Sensitive data = True, Used in reporting = True

  2. **ContactInfo**
     * `email`: string
     * `phone`: string
     * `address`: Address (reference)
     * *Settings*: Sensitive data = True, Used in reporting = False

  3. **Claim**
     * `claimId`: string
     * `policyNumber`: string (reference to Policy)
     * `claimType`: enum \["Auto", "Property", "Medical", "Liability"]
     * `incidentDate`: date
     * `reportedDate`: date
     * `status`: enum \["New", "Under Review", "Pending Documents", "Approved", "Denied", "Closed"]
     * `estimatedAmount`: number
     * `approvedAmount`: number
     * `documents`: array of Document (reference)
     * *Settings*: Sensitive data = False, Used in reporting = True

  4. **Document**
     * `documentId`: string
     * `documentType`: string
     * `fileName`: string
     * `fileUrl`: string
     * `uploadDate`: date
     * *Settings*: Sensitive data = False, Used in reporting = False
</Accordion>

<Accordion title="Process-specific data models">
  The company created multiple processes using the PDM:

  <Tabs>
    <Tab title="Auto Claim Processing">
      **Root**: ClaimProcess

      <Frame>
        ![Auto Claim Processing](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
      </Frame>

      **Data Structure**:

      * **ClaimProcess** (Process-specific type)
        * `claim`: Claim (reference from PDM)
        * `assignedAdjuster`: string
        * `vehicleInfo`: AutoClaimDetails (reference)
        * `processingStage`: enum \["Initial Review", "Damage Assessment", "Liability Determination", "Settlement Negotiation", "Payment Processing"]

      * **AutoClaimDetails** (Process-specific type)
        * `vehicleMake`: string
        * `vehicleModel`: string
        * `vehicleYear`: number
        * `vin`: string
        * `accidentLocation`: Address (reference from PDM)
        * `damageDescription`: string
    </Tab>

    <Tab title="Policy Renewal Process">
      **Root**: RenewalProcess

      <Frame>
        ![Policy Renewal Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example3.png)
      </Frame>

      **Data Structure**:

      * **RenewalProcess** (Process-specific type)
        * `customer`: Customer (reference from PDM)
        * `renewalDate`: date
        * `premiumChange`: number
        * `renewalStatus`: enum \["Pending Review", "Offer Generated", "Offer Sent", "Accepted", "Declined", "Expired"]
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Example use cases">
  <Tabs>
    <Tab title="Add an attribute">
      <video />

      1. A configurator adds a new attribute `loyaltyTier` to the Customer data type in the PDM.
      2. This attribute is an enum \["Bronze", "Silver", "Gold", "Platinum"].
      3. The new attribute automatically propagates to all processes using the Customer data type.
      4. The Policy Renewal Process now has access to the customer's loyalty tier without any process-level changes.
    </Tab>

    <Tab title="Remove a field">
      <Frame>
        <img alt="Remove field warning" />
      </Frame>

      1. A configurator tries to remove the `contactInformation` attribute from the Customer data type.
      2. The system displays a warning that the attribute is in use by multiple processes.
      3. The configurator is prevented from making the change until the references are resolved.
    </Tab>

    <Tab title="Library integration">
      <Frame>
        <img alt="Library integration" />
      </Frame>

      1. The company uses a "Common Insurance Standards" library with standardized data types.
      2. After setting the library as a dependency, they can use the library's "Vehicle" data type in their PDM.
      3. When the library updates, the configurator can choose to adopt the changes.
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Benefits demonstrated">
  <Card>
    This example shows how the Project Data Model:

    * **Ensures data consistency**: Core entities like Customer and Policy maintain consistent structures across all processes and resources.
    * **Promotes reusability**: Common data types are defined once and reused in in multiple processes, business rules, and other resources.
    * **Simplifies changes**: Updates to data types are propagated automatically to all processes.
    * **Enforces governance**: Sensitive data is marked at the project level for consistent handling.
    * **Allows flexibility**: Process-specific data can extend the PDM while maintaining core data integrity.
  </Card>
</Accordion>

## Export and import

You can export and import project data types to transfer them between projects or environments.

### Exporting

To export project data types:

1. Open the context menu on the Project Data Model page
2. Select **Export**
3. The data types are downloaded as a ZIP file

### Importing

To import project data types:

1. Open the context menu on the Project Data Model page
2. Select **Import**
3. Select the ZIP file exported from another project or environment
4. If data types with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting data type (or use **Apply to all**):
   * **Keep both** - imports the data type as a new copy alongside the existing one
   * **Replace** - overwrites the existing data type with the imported version
   * **Skip this one** - keeps the existing data type unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

***

## Best practices

<Check>
  **Plan before implementation**: Design your Project Data Model before creating processes to ensure consistency.
</Check>

<Check>
  **Always provide example values**: Example values will be used in data mapping and other operations.
</Check>

<Check>
  **Use descriptive names**: Choose clear, descriptive names for data types and attributes.
</Check>

<Check>
  **Document your model**: Add descriptions to data types and attributes for better understanding and for AI agents.
</Check>

<Check>
  **Consider reusability**: Design data types with reusability in mind across processes and resources.
</Check>

<Check>
  **Review impact of changes**: Before modifying data types, check their usage across processes.
</Check>

<Check>
  **Use libraries for cross-project standards**: For data types needed across multiple projects, define them in libraries.
</Check>

<Check>
  **Maintain regularly**: Periodically review and clean up unused data types.
</Check>

## Limitations

<Expandable title="Current limitations of the Project Data Model">
  <Warning>
    Custom Data Types from the Project or Library Data Model level cannot be modified at the resource level.
  </Warning>

  <Warning>
    Removing or changing Data Types in use may break resources using it.
  </Warning>

  <Warning>
    Project Data Model becomes read-only after version commitment. This is available for any configuration on commited versions; it applies also for resources data models.
  </Warning>

  <Warning>
    Library builds with breaking changes to Data Types require usage review.
  </Warning>

  <Info>
    Data Types defined at the Project or Library level can be referenced in the data models of Processes, Reusable Functions, and Reusable UI Templates.
  </Info>
</Expandable>

## Troubleshooting

<Accordion title="Cannot modify a referenced data type in process">
  <Steps>
    <Step title="Problem">
      You're trying to edit a data type from the PDM within a process, but the fields are read-only.
    </Step>

    <Step title="Solution">
      Make changes at the project level instead:

      1. Navigate to the Project Data Model
      2. Locate and edit the data type
      3. Save changes
      4. The changes will propagate to all processes
    </Step>
  </Steps>
</Accordion>

<Accordion title="Cannot delete a data type that is in use">
  <Steps>
    <Step title="Problem">
      You're trying to delete a data type, but receive an error that it's in use.
    </Step>

    <Step title="Solution">
      Either:

      * Remove all references to the data type first
      * Create a new version of your project to make the change
    </Step>
  </Steps>
</Accordion>

<Accordion title="References broken after type change">
  <Steps>
    <Step title="Problem">
      After changing a data type (e.g., from string to number), references are broken in processes.
    </Step>

    <Step title="Solution">
      Review affected processes and update references manually:

      1. Check the warning message that lists affected processes
      2. Open each process
      3. Update UI templates or other components that referenced the changed attribute
    </Step>
  </Steps>
</Accordion>

<Accordion title="Library update warning about breaking changes">
  <Steps>
    <Step title="Problem">
      When updating a library dependency, you receive warnings about breaking changes to data types.
    </Step>

    <Step title="Solution">
      Carefully review the changes and their impact before proceeding:

      1. Check which data types are affected
      2. Review how these types are used in your processes
      3. Decide whether to proceed with the update or maintain the current version
    </Step>
  </Steps>
</Accordion>

***

## Academy courses

<CardGroup>
  <Card title="Data Model 101 course" icon="graduation-cap" href="https://academy.flowx.ai/explore/data-model-101-0">
    Learn attribute types, JSON format, and data modeling fundamentals
  </Card>

  <Card title="Handle Dynamic Data course" icon="graduation-cap" href="https://academy.flowx.ai/explore/handle-dynamic-data-flowxai">
    Configure dynamic dropdowns and data-driven UI from process data
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**DataModel101**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/248681ec-3ba4-40e1-95ce-60a0856280ff/config/a38b8942-8eaf-41aa-8e80-e32d74bc9273/processes) project for hands-on data modeling examples.
</Tip>


# Custom Components
Source: https://docs.flowx.ai/5.9/docs/building-blocks/reusable-resources/custom-components

Create custom React components that integrate with FlowX process data and actions, extending the built-in component palette with your own UI elements.

## What are Custom Components?

Custom Components are developer-defined React components that you create in FlowX Designer and reference in UI Flows. Unlike [Reusable UI Templates](./reusable-ui) which use the visual component builder, Custom Components let you write actual React code to build complex, interactive UI elements.

<CardGroup>
  <Card title="Code-based" icon="code">
    Write React TypeScript/JavaScript directly in the Designer code editor
  </Card>

  <Card title="Data-connected" icon="link">
    Receive process data through input keys and trigger process actions
  </Card>

  <Card title="Reusable" icon="recycle">
    Define once in Reusable Resources, use across multiple User Tasks
  </Card>

  <Card title="Import/Export" icon="file-export">
    Export as ZIP and import into other projects
  </Card>
</CardGroup>

***

## When to use Custom Components

| Use case                                                  | Recommended approach                                               |
| --------------------------------------------------------- | ------------------------------------------------------------------ |
| Standard forms, layouts, navigation                       | Built-in components or [Reusable UI Templates](./reusable-ui)      |
| Complex interactive widgets (charts, maps, custom inputs) | **Custom Components**                                              |
| Third-party library integration                           | **Custom Components**                                              |
| Custom business logic in the UI                           | **Custom Components** + [Reusable Functions](./reusable-functions) |
| Reusable visual patterns without code                     | [Reusable UI Templates](./reusable-ui)                             |

***

## Creating a Custom Component

Custom Components are managed under **Reusable Resources** in your project.

<Steps>
  <Step title="Navigate to Custom Components">
    In the Designer, open your project and go to **Reusable Resources** → **Custom Components**.
  </Step>

  <Step title="Create a new component">
    Click the **+** button to create a new Custom Component. Fill in the creation modal:

    <Frame>
      ![Create Custom Component modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
    </Frame>

    | Field                 | Description                                                            |
    | --------------------- | ---------------------------------------------------------------------- |
    | **Name**              | Display name for the component                                         |
    | **Unique Identifier** | A unique string identifier used to reference the component in UI Flows |
    | **Platform**          | **Web** or **Mobile**                                                  |
    | **Description**       | Optional description of the component's purpose                        |
  </Step>

  <Step title="Write your component code">
    The component editor has three panels:

    * **Source Files** (left) — a file tree with your component's JSX, CSS, and `package.json`
    * **Code editor** (right) — edit the selected file
    * **Dependencies** (bottom-left) — lists available packages

    Each component is scaffolded with:

    * `identifier.jsx` — your React component code
    * `identifier.css` — component styles
    * `package.json` — dependency declarations

    **Available dependencies:**

    | Package        | Version | Purpose            |
    | -------------- | ------- | ------------------ |
    | `react`        | 18.3.1  | Core React library |
    | `react-dom`    | 18.3.1  | DOM rendering      |
    | `@emotion/css` | 11.13.5 | CSS-in-JS styling  |
    | `lodash`       | 4.17.21 | Utility functions  |
    | `axios`        | 1.13.2  | HTTP requests      |
    | `date-fns`     | 2.30.0  | Date manipulation  |
  </Step>

  <Step title="Configure input keys">
    Define **Input Keys** to specify which process data paths the component receives. These map process data model attributes to the component's `data` prop.

    For example, if your process data model has `application.metrics.revenue`, add it as an input key. The component receives it as `data['application.metrics.revenue']`.
  </Step>

  <Step title="Test and save">
    Use the **Test** button to preview your component with sample data. Click **Save** to persist your changes.

    You can also test end-to-end by starting a UI Flow that includes the component.
  </Step>
</Steps>

***

## Using Custom Components in UI Flows

Once defined, Custom Components can be added to User Tasks in your UI Flows.

<Steps>
  <Step title="Add to a User Task">
    In the UI Designer, drag a **Custom Component** element from the component palette into your User Task layout.
  </Step>

  <Step title="Select the component">
    In the properties panel, select your Custom Component by its **Identifier** (e.g., `MyCustomChart`).
  </Step>

  <Step title="Map input keys">
    Configure which process data paths are passed to the component. Use data model paths like `${application.user.profile}` to bind process data.

    <Frame>
      ![Custom Component parameters configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/custom_comps_params.png)
    </Frame>
  </Step>

  <Step title="Connect event handlers">
    If your component triggers actions (e.g., button clicks), connect them to process actions defined on the User Task node.
  </Step>
</Steps>

***

## Using Custom Components in Process User Tasks

The Process User Task host follows the same drag-and-drop authoring flow as UI Flows, with one extra concept: every Custom Component declares its own data model, kept distinct from process data so the component contract stays explicit at each use site.

<Steps>
  <Step title="Drop the Custom Component onto a User Task">
    In the Designer, open a Process and select a User Task node. From the component palette, drag the **Custom Component** element into the User Task layout, and pick your component by its identifier.
  </Step>

  <Step title="Configure INPUT mappings">
    On the Custom Component's properties panel, define how process data flows into the component. Map process attributes onto the slots declared on the component's input data model. The React SDK applies these mappings at runtime and the component receives only the data it declared.
  </Step>

  <Step title="Configure OUTPUT mappings">
    For components that trigger actions, define how the component's `saveData` is remapped back to process variables. The React SDK applies the OUTPUT mappings before the action's `saveData` is piped into the process state.
  </Step>

  <Step title="Connect process actions">
    Wire component-triggered actions to the actions defined on the User Task node, the same way you do for built-in components.
  </Step>
</Steps>

<Tip>
  The Custom Component editor lets you fill input parameters with sample data and preview the component without leaving the Designer. The same flow works for components that target both UI Flows and Process User Tasks.
</Tip>

<Note>
  Process User Tasks are rendered by the React SDK only in 5.8.0. The Phase 1 React-only limitation in the section below still applies: there is no Angular SDK support for Custom Components yet.
</Note>

***

## Example: Onboarding checklist

A progress tracker that displays a list of onboarding steps with completion status, driven by process data.

<Frame>
  ![Onboarding checklist custom component rendered output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_output_custom_component.png)
</Frame>

<Tabs>
  <Tab title="identifier.jsx">
    ```jsx theme={"system"}
    import React from "react";

    export default function OnboardingChecklist({ input }) {
      const steps = input?.data || [];
      const completed = steps.filter((s) => s.completed).length;
      const total = steps.length;
      const pct = total > 0 ? Math.round((completed / total) * 100) : 0;

      return (
        <div className="obc-root">
          <div className="obc-header">
            <span className="obc-title">Onboarding progress</span>
            <span className="obc-pct">{pct}%</span>
          </div>
          <div className="obc-bar-track">
            <div className="obc-bar-fill" style={{ width: `${pct}%` }} />
          </div>
          <ul className="obc-list">
            {steps.map((step, i) => (
              <li key={i} className={`obc-step ${step.completed ? "obc-done" : ""}`}>
                <span className="obc-icon">{step.completed ? "✓" : "○"}</span>
                <span>{step.label}</span>
              </li>
            ))}
          </ul>
        </div>
      );
    }
    ```
  </Tab>

  <Tab title="identifier.css">
    ```css theme={"system"}
    .obc-root {
      font-family: sans-serif;
      padding: 20px;
      border: 1px solid #e2e8f0;
      border-radius: 12px;
    }

    .obc-header {
      display: flex;
      justify-content: space-between;
      margin-bottom: 8px;
    }

    .obc-title {
      font-weight: 600;
      font-size: 14px;
      color: #1e293b;
    }

    .obc-pct {
      font-weight: 600;
      font-size: 14px;
      color: #10b981;
    }

    .obc-bar-track {
      height: 6px;
      background: #f1f5f9;
      border-radius: 3px;
      margin-bottom: 16px;
    }

    .obc-bar-fill {
      height: 100%;
      background: #10b981;
      border-radius: 3px;
      transition: width 0.3s ease;
    }

    .obc-list {
      list-style: none;
      margin: 0;
      padding: 0;
    }

    .obc-step {
      display: flex;
      align-items: center;
      gap: 10px;
      padding: 8px 0;
      font-size: 14px;
      color: #94a3b8;
    }

    .obc-step.obc-done {
      color: #1e293b;
    }

    .obc-icon {
      width: 20px;
      text-align: center;
      font-size: 14px;
    }

    .obc-step.obc-done .obc-icon {
      color: #10b981;
      font-weight: 700;
    }
    ```
  </Tab>

  <Tab title="Sample data">
    The component's `input.data` expects an array of step objects:

    ```json theme={"system"}
    [
      { "label": "Verify email address", "completed": true },
      { "label": "Complete personal details", "completed": true },
      { "label": "Upload ID document", "completed": false },
      { "label": "Sign agreement", "completed": false },
      { "label": "First deposit", "completed": false }
    ]
    ```
  </Tab>
</Tabs>

### Key patterns in this example

| Pattern                     | How it's used                                                       |
| --------------------------- | ------------------------------------------------------------------- |
| **Guard against undefined** | `input?.data \|\| []` prevents errors before process data loads     |
| **Scoped CSS**              | All classes prefixed with `obc-` to avoid style conflicts           |
| **No CSS import**           | The CSS file is loaded automatically by the runtime                 |
| **Derived state**           | Progress percentage calculated from the data, not stored separately |
| **Minimal dependencies**    | Only React — no additional packages needed                          |

<Tip>
  **Generating components with AI:** You can use the following prompt template to generate Custom Components with an AI assistant:

  *"Create a simple react component as a widget that \[description]. Rules: one jsx file + one css file, scoped CSS (no global styles), don't import the CSS file, contain dimensions, keep it simple. The component receives an `input` prop with a `data` property (initial value is undefined, guard against it). The data value should \[describe the shape]. Output a JSON dependencies list (ignoring react, @emotion/css, lodash, axios, date-fns)."*
</Tip>

***

## Component API reference

Custom Components receive the following props:

| Prop        | Type                               | Description                                           |
| ----------- | ---------------------------------- | ----------------------------------------------------- |
| `data`      | `Record<string, any>`              | Process data mapped through the configured input keys |
| `actions`   | `ProcessAction[]`                  | List of available process actions                     |
| `actionsFn` | `Record<string, () => Observable>` | Bound action functions keyed by action name           |

<Note>
  Custom Components run in the React SDK runtime. They have access to standard React APIs and a set of pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Custom npm packages cannot be added in Phase 1.
</Note>

***

## Import and export

Custom Components support the standard FlowX import/export workflow:

* **Export**: Select components and export as a ZIP file
* **Import**: Import ZIP files into other projects
* **Conflict resolution**: When importing, choose to **Keep both**, **Replace**, or **Skip** for each component

***

## Permissions

Custom Components are controlled by the `CUSTOM_COMPONENT` resource type in the authorization system.

| Permission                | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `CUSTOM_COMPONENT` read   | View custom components in a project                  |
| `CUSTOM_COMPONENT` write  | Create and edit custom components                    |
| `CUSTOM_COMPONENT` delete | Delete custom components                             |
| Import/Export             | Requires standard resource import/export permissions |

By default, the **Project Owner** role has full Custom Component permissions.

***

## Limitations (Phase 1)

<Warning>
  Phase 1 limitations — these will be addressed in future releases:

  * **React only** — Custom Components are not supported in Angular SDK
  * **Pre-defined dependencies** — A curated set of packages is available (React, Emotion, Lodash, Axios, date-fns). Custom npm packages cannot be added in Phase 1.
  * **Browser-side bundling** — Components are bundled in the browser, which limits complexity
  * **No server-side rendering** — Components render client-side only
</Warning>

***

## Related resources

<CardGroup>
  <Card title="Reusable UI Templates" icon="layer-group" href="./reusable-ui">
    Visual, no-code reusable UI patterns
  </Card>

  <Card title="Reusable Functions" icon="function" href="./reusable-functions">
    Reusable business logic functions
  </Card>

  <Card title="UI Flows" icon="window" href="../ui-flows">
    Building user interfaces with FlowX
  </Card>

  <Card title="Event Handlers" icon="bolt" href="../ui-designer/event-handlers">
    Configuring event handlers on components
  </Card>
</CardGroup>


# Reusable Functions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/reusable-resources/reusable-functions

Create and manage business logic components that can be reused across multiple processes in your FlowX.AI applications.

<Frame>
  ![Reusable Functions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr4.png)
</Frame>

## What are Reusable Functions?

Reusable Functions are self-contained business logic components that process data according to your specified rules. Instead of writing the same logic multiple times across different processes, you can:

* Define the logic once in a reusable function
* Use the function in multiple processes through data mapping
* Automatically propagate updates to all instances when you modify the function

<Note>
  Functions execute in isolated environments and cannot be edited within individual process contexts. All changes must be made to the original function definition.
</Note>

## Key benefits

<CardGroup>
  <Card title="Reduce duplication" icon="copy">
    Write business logic once and reuse it across multiple processes
  </Card>

  <Card title="Improve maintainability" icon="wrench">
    Update logic in one place and automatically apply changes everywhere
  </Card>

  <Card title="Ensure consistency" icon="shield-check">
    Standardize business rules across your entire application
  </Card>

  <Card title="Increase efficiency" icon="clock">
    Spend less time rewriting similar logic for different processes
  </Card>
</CardGroup>

## Before you begin

Make sure you have:

* Access to the FlowX.AI Designer
* Appropriate permissions to create and manage reusable resources
* A clear understanding of the business logic you want to implement

## Create a reusable function

<Steps>
  <Step title="Access the Functions section">
    1. In FlowX.AI Designer, go to your project
    2. Navigate to **Reusable Resources** > **Functions**
    3. Click the **+** icon to create a new function

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr3.png)
    </Frame>
  </Step>

  <Step title="Configure basic settings">
    1. Enter a descriptive name for your function
    2. Add an optional description explaining the function's purpose
    3. Click **Save** to create the function and open the editor

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr5.png)
    </Frame>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr6.png)
    </Frame>
  </Step>

  <Step title="Define the data model">
    1. Go to the **Model** tab
    2. Add attributes that your function will work with:
       * Click **Add Attribute** to create new fields
       * Set attribute types by selecting existing objects from your project
       * Define nested structures as needed

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr1.png)
    </Frame>

    <Info>
      Functions support both primitive data types (string, number, boolean) and complex object data types for input and output parameters. See [Understanding Data Types](#understanding-data-types) for more information.
    </Info>

    <Tip>
      Define **both input and output fields** in your data model. Later, you'll select which fields are inputs (Input Parameters tab) and which are outputs (Output Parameters tab).
    </Tip>

    <Tabs>
      <Tab title="getBasicFacts - Primitive">
        **Primitive types only** — all fields are flat (string/number), no nesting. Use this pattern when your function takes a single input value and returns several scalar results.

        ```json theme={"system"}
        {
          "question": "string",
          "universeAge": "number",
          "galaxyCount": "number",
          "speedOfLight": "number",
          "explanation": "string"
        }
        ```

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr7.png)
        </Frame>
      </Tab>

      <Tab title="getUniverseOverview - Object">
        **Object types with one level of nesting** — inputs and outputs are objects, each containing a small set of related fields. Use this pattern when your function takes structured query parameters and returns a structured result object.

        * **Inputs**: `query` (topic + detail level) and `user_preferences` (formatting options)
        * **Outputs**: `universe` (facts + composition) and `explanation` (summary + key facts)

        ```json theme={"system"}
        {
          "query": {
            "topic": "string",
            "detail_level": "string"
          },
          "user_preferences": {
            "scientific_notation": "boolean",
            "units": "string"
          },
          "universe": {
            "basicFacts": {
              "age": "number",
              "galaxyCount": "number",
              "starCount": "number"
            },
            "composition": {
              "darkMatter": "number",
              "darkEnergy": "number",
              "ordinaryMatter": "number"
            }
          },
          "explanation": {
            "summary": "string",
            "keyFacts": "array",
            "confidence": "number"
          }
        }
        ```

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr8.png)
        </Frame>
      </Tab>

      <Tab title="myFirstFunction - Complex">
        **Deeply nested objects with multiple input groups** — inputs are split across three distinct objects (`request`, `user_context`, `constraints`), with `user_context` containing a nested `preferences` sub-object. Outputs include three separate result objects (`universe`, `timeline`, `explanation`). Use this pattern when you need to model richer context or pass multiple independent parameter groups to a single function.

        Compared to `getUniverseOverview`, this example shows: more input objects, deeper nesting (e.g. `user_context.preferences`), and more output fields covering a broader data structure.

        Comprehensive data model for explaining the universe:

        ```json theme={"system"}
        {
          "request": {
            "topic": "string",
            "scope": "string",
            "scientific_level": "string"
          },
          "user_context": {
            "background": "string",
            "preferences": {
              "include_equations": "boolean",
              "visual_aids": "boolean"
            }
          },
          "constraints": {
            "max_length": "number",
            "language": "string"
          },
          "universe": {
            "fundamentalConstants": {
              "speedOfLight": "number",
              "gravitationalConstant": "number",
              "hubbleConstant": "number"
            },
            "composition": {
              "darkMatter": "number",
              "darkEnergy": "number",
              "ordinaryMatter": "number"
            },
            "structures": {
              "galaxies": "number",
              "stars": "number",
              "planets": "number"
            }
          },
          "timeline": {
            "bigBang": "number",
            "firstStars": "number",
            "earthFormation": "number"
          },
          "explanation": {
            "summary": "string",
            "keyInsights": "array",
            "confidence": "number"
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure input parameters">
    1. Switch to the **Input Parameters** tab
    2. Select the fields from your data model that your function needs as input
    3. Expand objects to choose specific properties

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr2.png)
    </Frame>

    <Tabs>
      <Tab title="getBasicFacts - Input">
        Select input fields from the data model for basic universe queries:

        ```json Input parameter selection from data model theme={"system"}
        [
          "question"
        ]
        ```

        From the data model fields:

        * ✅ **question** (string) - SELECT as input
        * ❌ **universeAge** (number) - Do NOT select (output only)
        * ❌ **galaxyCount** (number) - Do NOT select (output only)
        * ❌ **speedOfLight** (number) - Do NOT select (output only)
        * ❌ **explanation** (string) - Do NOT select (output only)

        Example input mapping from process:

        ```json theme={"system"}
        {
          "question": "processData.userQuery"
        }
        ```

        <Info>
          Select only the fields your function needs as input from the data model. The output fields will be selected in the Output Parameters tab.
        </Info>
      </Tab>

      <Tab title="getUniverseOverview - Input">
        Select input fields from the data model for detailed queries:

        ```json Input parameter selection from data model theme={"system"}
        [
          "query",
          "user_preferences"
        ]
        ```

        From the data model fields:

        * ✅ **query** (object) - SELECT as input
        * ✅ **user\_preferences** (object) - SELECT as input
        * ❌ **universe** (object) - Do NOT select (output only)
        * ❌ **explanation** (object) - Do NOT select (output only)

        Example input mapping from process:

        ```json theme={"system"}
        {
          "query": "processData.universeQuery",
          "user_preferences": "processData.userSettings"
        }
        ```

        <Info>
          Select the input objects from your data model. The function will use these to customize its output behavior.
        </Info>
      </Tab>

      <Tab title="myFirstFunction - Input">
        Select input fields from the data model for complex universe explanations:

        ```json Input parameter selection from data model theme={"system"}
        [
          "request",
          "user_context", 
          "constraints"
        ]
        ```

        From the data model fields:

        * ✅ **request** (object) - SELECT as input
        * ✅ **user\_context** (object) - SELECT as input
        * ✅ **constraints** (object) - SELECT as input
        * ❌ **universe** (object) - Do NOT select (output only)
        * ❌ **timeline** (object) - Do NOT select (output only)
        * ❌ **explanation** (object) - Do NOT select (output only)

        Example input mapping from process:

        ```json theme={"system"}
        {
          "request": "processData.universeRequest",
          "user_context": "processData.userProfile",
          "constraints": "processData.outputConstraints"
        }
        ```

        <Info>
          Select the input objects that control how the function behaves. The output objects will be configured in the Output Parameters tab.
        </Info>
      </Tab>
    </Tabs>

    <Tip>
      Define clear input contracts to make your functions truly reusable across different contexts. Match input complexity to function complexity.
    </Tip>
  </Step>

  <Step title="Set output parameters">
    1. Go to the **Output Parameters** tab
    2. Select the fields from your data model that the function returns
    3. Choose individual fields or entire objects as needed

    <Tabs>
      <Tab title="getBasicFacts - Output">
        Select output fields from the data model for basic universe facts:

        ```json Output parameter selection from data model theme={"system"}
        [
          "universeAge",
          "galaxyCount", 
          "speedOfLight",
          "explanation"
        ]
        ```

        From the data model fields:

        * ❌ **question** (string) - Do NOT select (input only)
        * ✅ **universeAge** (number) - SELECT as output
        * ✅ **galaxyCount** (number) - SELECT as output
        * ✅ **speedOfLight** (number) - SELECT as output
        * ✅ **explanation** (string) - SELECT as output

        <Info>
          Select the fields that your function calculates and returns. These were the fields showing incorrectly in your Input Parameters tab.
        </Info>
      </Tab>

      <Tab title="getUniverseOverview - Output">
        Select output fields from the data model for detailed universe data:

        ```json Output parameter selection from data model theme={"system"}
        [
          "universe",
          "universe.basicFacts",
          "universe.composition",
          "explanation",
          "explanation.summary",
          "explanation.keyFacts",
          "explanation.confidence"
        ]
        ```

        From the data model fields:

        * ❌ **query** (object) - Do NOT select (input only)
        * ❌ **user\_preferences** (object) - Do NOT select (input only)
        * ✅ **universe** (object) - SELECT as output
        * ✅ **explanation** (object) - SELECT as output

        <Info>
          Select the objects that your function generates. You can choose entire objects or specific nested properties based on what your process needs.
        </Info>
      </Tab>

      <Tab title="myFirstFunction - Output">
        Select output fields from the data model for complete universe explanation:

        ```json Output parameter selection from data model theme={"system"}
        [
          "universe",
          "universe.fundamentalConstants",
          "universe.composition", 
          "universe.structures",
          "timeline",
          "explanation",
          "explanation.keyInsights"
        ]
        ```

        From the data model fields:

        * ❌ **request** (object) - Do NOT select (input only)
        * ❌ **user\_context** (object) - Do NOT select (input only)
        * ❌ **constraints** (object) - Do NOT select (input only)
        * ✅ **universe** (object) - SELECT as output
        * ✅ **timeline** (object) - SELECT as output
        * ✅ **explanation** (object) - SELECT as output

        <Info>
          Select the objects that contain the universe explanation results. You can choose entire objects or drill down to specific properties you need.
        </Info>
      </Tab>
    </Tabs>

    <Tip>
      You can select entire objects (like `universe`) or specific properties (like `universe.basicFacts.age`) depending on what your process needs.
    </Tip>
  </Step>

  <Step title="Implement the business logic">
    1. Navigate to the **Script** tab
    2. Choose your programming language (JavaScript or Python)
    3. Write your business logic using the appropriate data format

    <Tabs>
      <Tab title="getBasicFacts - Primitive">
        Simple function with basic universe facts:

        <CodeGroup>
          ```javascript getBasicFacts theme={"system"}
          // Function format: functions.projectName.functionName(input)
          function functions.cosmos.getBasicFacts(question) {
              // Access input parameter: input.question
              const userQuestion = input.question || "What is the universe?";
              
              // Basic universe facts
              output.universeAge = 13.8; // billion years
              output.galaxyCount = 2000; // billion galaxies
              output.speedOfLight = 299792458; // m/s
              output.explanation = "The universe is 13.8 billion years old and contains about 2 trillion galaxies.";
          }
          ```

          ```python getBasicFacts (Python) theme={"system"}
          # Function format: functions.projectName.functionName(input)
          # function functions.cosmos.getBasicFacts(question)
          # Access input parameter: input.question
          user_question = input.question or "What is the universe?"

          # Basic universe facts
          output.universeAge = 13.8  # billion years
          output.galaxyCount = 2000  # billion galaxies
          output.speedOfLight = 299792458  # m/s
          output.explanation = "The universe is 13.8 billion years old and contains about 2 trillion galaxies."
          ```
        </CodeGroup>
      </Tab>

      <Tab title="getUniverseOverview - Object">
        Function with structured universe data:

        <CodeGroup>
          ```javascript getUniverseOverview theme={"system"}
          // Function format: functions.projectName.functionName(input)
          function functions.cosmos.getUniverseOverview(query) {
              // Access input parameters: input.query.topic, input.query.detail_level, input.user_preferences
              const detailLevel = input.query?.detail_level || "basic";
              const userPrefs = input.user_preferences || {};
              
              // Structured universe data
              output.universe = {
                  basicFacts: {
                      age: 13.8, // billion years
                      galaxyCount: 2000, // billion
                      starCount: 200000000 // billion billion (2×10^23)
                  },
                  composition: {
                      darkMatter: 26.8, // percentage
                      darkEnergy: 68.3, // percentage
                      ordinaryMatter: 4.9 // percentage
                  }
              };
              
              output.explanation = {
                  summary: "The universe is mostly dark matter and dark energy, with ordinary matter making up less than 5%.",
                  keyFacts: [
                      "Universe is 13.8 billion years old",
                      "Contains 2 trillion galaxies",
                      "Dark energy causes expansion"
                  ],
                  confidence: 0.9
              };
          }
          ```

          ```python getUniverseOverview (Python) theme={"system"}
          # Access input parameters: input.query.detail_level, input.user_preferences
          detail_level = input.query.get('detail_level', 'basic') if input.query else 'basic'
          user_prefs = input.user_preferences or {}

          # Structured universe data
          output.universe = {
              'basicFacts': {
                  'age': 13.8,  # billion years
                  'galaxyCount': 2000,  # billion
                  'starCount': 200000000  # billion billion
              },
              'composition': {
                  'darkMatter': 26.8,
                  'darkEnergy': 68.3,
                  'ordinaryMatter': 4.9
              }
          }

          output.explanation = {
              'summary': 'The universe is mostly dark matter and dark energy.',
              'keyFacts': ['Universe is 13.8 billion years old', 'Contains 2 trillion galaxies'],
              'confidence': 0.9
          }
          ```
        </CodeGroup>
      </Tab>

      <Tab title="myFirstFunction - Complex">
        Comprehensive function with detailed universe data:

        <CodeGroup>
          ```javascript myFirstFunction theme={"system"}
          // Function format: functions.projectName.functionName(input)
          function functions.cosmos.myFirstFunction(request) {
              // Access comprehensive input parameters
              const topic = input.request?.topic || "general";
              const scope = input.request?.scope || "basic";
              const scientificLevel = input.request?.scientific_level || "beginner";
              const userBackground = input.user_context?.background || "general";
              const maxLength = input.constraints?.max_length || 10000;
              
              // Comprehensive universe explanation
              output.universe = {
                  fundamentalConstants: {
                      speedOfLight: 299792458, // m/s
                      gravitationalConstant: 6.674e-11,
                      hubbleConstant: 70 // km/s/Mpc
                  },
                  composition: {
                      darkMatter: 26.8,
                      darkEnergy: 68.3,
                      ordinaryMatter: 4.9
                  },
                  structures: {
                      galaxies: 2e12, // 2 trillion
                      stars: 1e24, // 1 septillion
                      planets: 1e24 // estimated
                  }
              };
              
              output.timeline = {
                  bigBang: 13.8e9, // years ago
                  firstStars: 13.6e9, // years ago
                  earthFormation: 4.6e9 // years ago
              };
              
              output.explanation = {
                  summary: "The universe began 13.8 billion years ago and is dominated by dark matter and dark energy.",
                  keyInsights: [
                      "Universe is expanding and accelerating",
                      "Most matter is invisible (dark matter)",
                      "Contains billions of galaxies with trillions of stars"
                  ],
                  confidence: 0.85
              };
          }
          ```

          ```python myFirstFunction (Python) theme={"system"}
          # Access comprehensive input parameters
          topic = input.request.get('topic', 'general') if input.request else 'general'
          scope = input.request.get('scope', 'basic') if input.request else 'basic'
          scientific_level = input.request.get('scientific_level', 'beginner') if input.request else 'beginner'
          user_background = input.user_context.get('background', 'general') if input.user_context else 'general'
          max_length = input.constraints.get('max_length', 10000) if input.constraints else 10000

          # Comprehensive universe explanation
          output.universe = {
              'fundamentalConstants': {
                  'speedOfLight': 299792458,
                  'gravitationalConstant': 6.674e-11,
                  'hubbleConstant': 70
              },
              'composition': {
                  'darkMatter': 26.8,
                  'darkEnergy': 68.3,
                  'ordinaryMatter': 4.9
              },
              'structures': {
                  'galaxies': 2e12,
                  'stars': 1e24,
                  'planets': 1e24
              }
          }

          output.timeline = {
              'bigBang': 13.8e9,
              'firstStars': 13.6e9,
              'earthFormation': 4.6e9
          }

          output.explanation = {
              'summary': 'The universe began 13.8 billion years ago.',
              'keyInsights': ['Universe is expanding', 'Most matter is dark matter'],
              'confidence': 0.85
          }
          ```
        </CodeGroup>
      </Tab>
    </Tabs>

    <Note>
      Always use `input.attribute` format to access function parameters and `output.attribute` to set return values.
    </Note>
  </Step>

  <Step title="Test your function">
    1. Go to the **Test** tab
    2. Add sample data for your input parameters
    3. Click **Test** to execute the function
    4. Review the output to ensure your logic works correctly
    5. Save your function when testing is successful
  </Step>
</Steps>

## Use functions in processes

After creating a reusable function, you can use it in your business processes through Business Rule actions, or reference it within other reusable functions.

### Where you can reference functions

Reusable functions can be referenced in two contexts:

* **Business Rule actions** within process nodes
* **Other reusable functions** to create composite logic

### Function referencing syntax

When referencing a reusable function, use this format:

```javascript theme={"system"}
functions.projectName.functionName(input.params)
```

Where:

* `functions` - Convention to reference any reusable function
* `projectName` - Name of the project/library where the function is defined
* `functionName` - Name of the reusable function
* `input.params` - Input parameters using local process variables

<CodeGroup>
  ```javascript Primitive parameter example theme={"system"}
  functions.academy.calculateMaxLoanAmount(input.monthlySalary)
  ```

  ```javascript Object parameter example theme={"system"}
  functions.loanLibrary.calculateLoan(input.client)
  ```

  ```javascript Multiple parameters example theme={"system"}
  functions.library1.calculateAgeFromSSN(input.client.ssn)
  ```
</CodeGroup>

### Add a function to a process

1. Open your process definition in FlowX.AI Designer
2. Select the node where you want to add business logic
3. Create a new **Business Rule** action
4. Reference your reusable function using the syntax above
5. Configure data mapping between your process and the function

### Configure data mapping

Data mapping connects your process data to the function's input and output parameters.

<Tabs>
  <Tab title="Input mapping">
    Map process variables to function input parameters:

    <Tabs>
      <Tab title="getBasicFacts Mapping">
        Simple input mapping for basic universe queries:

        ```json getBasicFacts input mapping theme={"system"}
        {
          "question": "processData.userQuestion"
        }
        ```

        Process context example:

        ```json theme={"system"}
        {
          "processData": {
            "userQuestion": "What is the universe?"
          }
        }
        ```
      </Tab>

      <Tab title="getUniverseOverview Mapping">
        Structured input mapping for detailed queries:

        ```json getUniverseOverview input mapping theme={"system"}
        {
          "query": "processData.universeRequest",
          "query.topic": "processData.selectedTopic", 
          "query.detail_level": "processData.requestedDetail",
          "user_preferences": "processData.userProfile.preferences"
        }
        ```

        Process context example:

        ```json theme={"system"}
        {
          "processData": {
            "universeRequest": {
              "topic": "dark_matter",
              "detail_level": "intermediate"
            },
            "selectedTopic": "composition",
            "requestedDetail": "moderate",
            "userProfile": {
              "preferences": {
                "scientific_notation": true,
                "units": "metric"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="myFirstFunction Mapping">
        Comprehensive input mapping for complex universe explanations:

        ```json myFirstFunction input mapping theme={"system"}
        {
          "request": "processData.universeInquiry",
          "request.topic": "processData.specificSubject",
          "request.scope": "processData.explanationScope",
          "request.scientific_level": "processData.userExpertiseLevel",
          "user_context": "processData.userContext",
          "constraints": "processData.outputLimitations"
        }
        ```

        Process context example:

        ```json theme={"system"}
        {
          "processData": {
            "universeInquiry": {
              "topic": "cosmic_evolution",
              "scope": "comprehensive",
              "scientific_level": "advanced"
            },
            "specificSubject": "big_bang_theory",
            "explanationScope": "timeline_focused",
            "userExpertiseLevel": "graduate_level",
            "userContext": {
              "background": "physics_student",
              "preferences": {
                "include_equations": true,
                "visual_aids": false
              }
            },
            "outputLimitations": {
              "max_length": 5000,
              "language": "english"
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    <Warning>
      Ensure data types match between your process variables and function parameters to avoid runtime errors. Use dot notation for nested object properties.
    </Warning>
  </Tab>

  <Tab title="Output mapping">
    Specify where to store function outputs in your process data:

    <Tabs>
      <Tab title="getBasicFacts Mapping">
        Map primitive outputs to process variables:

        ```json getBasicFacts output mapping theme={"system"}
        {
          "processData.universeAge": "output.universeAge",
          "processData.totalGalaxies": "output.galaxyCount",
          "processData.lightSpeed": "output.speedOfLight",
          "processData.summary": "output.explanation"
        }
        ```
      </Tab>

      <Tab title="getUniverseOverview Mapping">
        Map structured outputs to process data:

        ```json getUniverseOverview output mapping theme={"system"}
        {
          "processData.cosmicData": "output.universe",
          "processData.universeAge": "output.universe.basicFacts.age",
          "processData.composition": "output.universe.composition",
          "processData.explanation": "output.explanation",
          "processData.confidence": "output.explanation.confidence"
        }
        ```
      </Tab>

      <Tab title="myFirstFunction Mapping">
        Map comprehensive outputs to process variables:

        ```json myFirstFunction output mapping theme={"system"}
        {
          "processData.universeData": "output.universe",
          "processData.constants": "output.universe.fundamentalConstants",
          "processData.timeline": "output.timeline",
          "processData.explanation": "output.explanation",
          "processData.insights": "output.explanation.keyInsights"
        }
        ```
      </Tab>
    </Tabs>

    <Info>
      You can map entire objects or specific properties. Use dot notation to access nested properties from complex function outputs.
    </Info>
  </Tab>
</Tabs>

### Use functions within functions

You can create composite business logic by calling one reusable function from within another reusable function. This enables you to build complex functionality from smaller, focused components.

<Steps>
  <Step title="Reference the function">
    Use the standard function referencing syntax within your script:

    ```javascript theme={"system"}
    // Call another function and use its output
    const maxLoan = functions.academy.calculateMaxLoanAmount(input.monthlySalary);

    // Use the result in further calculations
    const loanDetails = functions.loanLibrary.calculateLoan({
        principal: maxLoan,
        rate: input.interestRate,
        term: input.loanTerm
    });

    // Set the final output
    output.integratedLoanData = loanDetails;
    ```
  </Step>

  <Step title="Handle data flow">
    Ensure proper data flow between functions:

    * **Input format**: Always use `input.attribute` to access function parameters
    * **Function calls**: Use `functions.projectName.functionName(parameters)` format
    * **Output assignment**: Set results to `output.attribute`
  </Step>

  <Step title="Test composite functions">
    Test thoroughly to ensure all nested function calls work correctly:

    1. Test each individual function first
    2. Test the composite function with realistic data
    3. Verify the data flows correctly between function calls
    4. Check error handling when nested functions fail
  </Step>
</Steps>

<CodeGroup>
  ```javascript integratedLoanCalculator example theme={"system"}
  // Function that calculates loan based on salary using other functions
  function functions.loanProject.integratedLoanCalculator(clientData) {
      // Calculate how much loan a person can get based on their salary
      const maxAmount = functions.academy.calculateMaxLoanAmount(input.clientData.monthlySalary);
      
      // Use that amount with calculateLoan function to compute detailed loan information
      const loanDetails = functions.loanLibrary.calculateLoan({
          principal: maxAmount,
          monthlyRate: input.clientData.monthlyRate,
          numberOfPayments: input.clientData.numberOfPayments,
          client: input.clientData
      });
      
      // The final computed result is passed into the output
      output.integratedLoanData = loanDetails;
  }
  ```

  ```python integratedLoanCalculator (Python) theme={"system"}
  # Calculate how much loan a person can get based on their salary
  max_amount = functions.academy.calculateMaxLoanAmount(input.clientData.monthlySalary)

  # Use that amount with calculateLoan function to compute detailed loan information
  loan_details = functions.loanLibrary.calculateLoan({
      'principal': max_amount,
      'monthlyRate': input.clientData.monthlyRate,
      'numberOfPayments': input.clientData.numberOfPayments,
      'client': input.clientData
  })

  # The final computed result is passed into the output
  output.integratedLoanData = loan_details
  ```
</CodeGroup>

<Warning>
  When using functions within functions, ensure all referenced functions exist in your project and have compatible input/output formats.
</Warning>

## Manage functions

### View function usage

To see where a function is used:

1. Select the function in **Reusable Resources** > **Functions**
2. Click the **Usages** tab
3. Review all processes and nodes that reference the function

<Info>
  The system displays a resource usage modal when you make changes that might affect existing implementations.
</Info>

### Update functions

When you modify a reusable function:

* Changes automatically propagate to all instances
* Existing process instances may need to restart to pick up updates
* The system preserves instance-specific configurations like data mapping

### Change programming languages

You can change a function's programming language after creation:

1. Open the function editor
2. Go to the **Script** tab
3. Select a different language from the dropdown
4. Rewrite your logic in the new language
5. Test thoroughly before saving

<Note>
  The system shows a usage modal to help you understand the impact of language changes on existing implementations.
</Note>

## Understanding data types

Reusable functions support two categories of data types for input and output parameters:

### Primitive data types

Primitive types represent single, simple values. They are the basic building blocks of data.

Available primitive types:

* **string** - Text values (for example, "John Doe," "active")
* **number** - Numeric values (for example, 42, 3.14, 13.8)
* **boolean** - True/false values (for example, true, false)

When to use primitives:

* Simple calculations requiring single values
* Basic status flags or indicators
* Individual measurements or counts
* Simple user inputs

Example - Primitive function:

```json theme={"system"}
{
  "salary": 5000,           // number
  "approved": true,         // boolean
  "status": "active"        // string
}
```

### Complex object data types

Complex types are structured collections of related data, containing multiple fields that can include both primitives and nested objects.

Available complex types:

* **object** - Structured data with named properties
* **array** - Ordered collections of values
* **nested objects** - Objects containing other objects

When to use complex types:

* Grouping related information together
* Representing real-world entities (customers, orders, products)
* Handling structured business data
* Managing hierarchical relationships

Example - Complex object function:

```json theme={"system"}
{
  "customer": {                    // object
    "personalInfo": {              // nested object
      "name": "John Doe",          // string
      "age": 35                    // number
    },
    "accounts": [                  // array
      {
        "type": "checking",
        "balance": 5000.00
      }
    ]
  },
  "preferences": {                 // object
    "notifications": true,         // boolean
    "language": "en"              // string
  }
}
```

### Key differences

| Aspect             | Primitive Types           | Complex Object Types                                                  |
| ------------------ | ------------------------- | --------------------------------------------------------------------- |
| Structure          | Single value              | Multiple related values                                               |
| Nesting            | Not applicable            | Can contain nested structures                                         |
| Access pattern     | Direct value access       | Dot notation for properties (for example, customer.personalInfo.name) |
| Use case           | Simple, standalone data   | Related data that should be grouped                                   |
| Mapping complexity | Simple one-to-one mapping | Can map entire objects or individual properties                       |

### Choosing the right data type

<Tabs>
  <Tab title="Use primitives when">
    * Working with single, independent values
    * Performing basic calculations
    * Storing simple flags or settings
    * Handling individual measurements

    **Example:** Calculating tax on a single amount, validating a single field
  </Tab>

  <Tab title="Use complex objects when">
    * Data represents a business entity
    * Multiple related values should stay together
    * You need hierarchical data structures
    * Function processes grouped information

    **Example:** Processing a loan application, validating customer information
  </Tab>
</Tabs>

<Info>
  **Best practice:** Start with primitives for simple functions. Upgrade to complex objects when you find yourself passing multiple related parameters or need better data organization.
</Info>

## Export and import

You can export and import reusable functions to transfer them between projects or environments.

### Exporting

To export a reusable function:

1. Navigate to **Reusable Resources** > **Functions**
2. Open the context menu for the function you want to export
3. Select **Export**
4. The function is downloaded as a ZIP file

### Importing

To import reusable functions:

1. Navigate to **Reusable Resources** > **Functions**
2. Open the context menu and select **Import from ZIP**
3. Select the ZIP file exported from another project or environment
4. If functions with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting function (or use **Apply to all**):
   * **Keep both** - imports the function as a new copy alongside the existing one
   * **Replace** - overwrites the existing function with the imported version
   * **Skip this one** - keeps the existing function unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

***

## Best practices

### Design principles

<AccordionGroup>
  <Accordion title="Single responsibility">
    Each function should serve one specific, well-defined purpose. Avoid creating functions that handle multiple unrelated tasks.
  </Accordion>

  <Accordion title="Clear interfaces">
    Define precise input and output parameters. Well-defined interfaces make functions easier to understand and use correctly.
  </Accordion>

  <Accordion title="Self-contained logic">
    Functions shouldn't depend on external state or global variables. All necessary data should come through input parameters.
  </Accordion>

  <Accordion title="Predictable behavior">
    The same inputs should always produce the same outputs. Avoid non-deterministic behavior in your business logic.
  </Accordion>
</AccordionGroup>

### Development workflow

1. **Define data model first**: Always establish your data structure before writing code
2. **Specify parameters early**: Define inputs and outputs before implementing logic
3. **Use descriptive names**: Choose clear, business-oriented function names
4. **Test thoroughly**: Validate functions with realistic data before deployment
5. **Handle errors gracefully**: Implement thorough error handling in your business logic

### Organization strategies

* **Group related functions**: Organize functions by business domain or use case
* **Follow naming conventions**: Establish consistent patterns for function names
* **Document extensively**: Include clear descriptions and usage examples
* **Version carefully**: Use project versioning to manage function changes safely

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Function not executing">
    **Possible causes:**

    * Incorrect input parameter mapping
    * Data type mismatches between process and function
    * Missing required input parameters
    * Runtime errors in function logic

    **Solutions:**

    * Verify all input mappings are correct
    * Check data types match between source and target
    * Ensure all required parameters have values
    * Review function logs for error details
  </Accordion>

  <Accordion title="Unexpected output">
    **Possible causes:**

    * Incorrect output parameter mapping
    * Logic errors in function implementation
    * Invalid test data during development

    **Solutions:**

    * Validate output parameter configuration
    * Test function with realistic data
    * Review business logic implementation
    * Check data transformations within the function
  </Accordion>

  <Accordion title="Performance issues">
    **Possible causes:**

    * Complex data processing logic
    * Inefficient algorithms
    * Large data structures

    **Solutions:**

    * Optimize function algorithms
    * Simplify data models where possible
    * Consider breaking complex functions into smaller components
    * Monitor execution times in process context
  </Accordion>
</AccordionGroup>

### Debugging strategies

1. **Use the test environment**: Always test functions thoroughly before deploying to production
2. **Start simple**: Build and test functions incrementally rather than implementing everything at once
3. **Use realistic data**: Test with data that matches your production scenarios
4. **Verify outputs**: Carefully check that function outputs match your expectations
5. **Add logging**: Include console output in your function logic to trace execution

## Function execution context

### Function format and syntax

All reusable functions follow a consistent format and syntax:

<CodeGroup>
  ```javascript Function declaration format theme={"system"}
  function functions.projectName.functionName(parameterName) {
      // Function implementation
  }
  ```

  ```javascript Function reference format theme={"system"}
  functions.projectName.functionName(input.params)
  ```
</CodeGroup>

**Key format rules:**

* **Function declaration**: `functions.projectName.functionName(parameters)`
* **Input access**: Always use `input.attribute` to access function parameters
* **Output assignment**: Use `output.attribute` to set return values
* **Function calls**: Reference other functions using `functions.projectName.functionName(params)`

### Data access patterns

When functions execute within processes, they have access to:

* **Input parameters**: Mapped from process data according to your configuration
* **Output object**: Used to return processed data back to the process
* **Standard libraries**: Built-in functions available in JavaScript or Python
* **Error handling**: Mechanisms to report execution problems back to the process

<Tabs>
  <Tab title="Input format">
    Access function input using the `input.attribute` format:

    ```javascript theme={"system"}
    // Access input parameters
    const salary = input.monthlySalary;
    const client = input.client;
    ```
  </Tab>

  <Tab title="Output format">
    Set function output using the `output` object:

    ```javascript theme={"system"}
    // Primitive output
    output = monthlySalary * 48;

    // Object output
    output.computedLoan = {
        principal: input.principal,
        monthlyPayment: monthlyPayment
    };
    ```
  </Tab>
</Tabs>

<Warning>
  Always verify that your input format (`input.attribute`) matches the parameter names defined in your function to avoid runtime errors.
</Warning>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can you change a reusable function's programming language after creation?">
    Yes, you can change a function's programming language after creation. Navigate to the **Script** tab, select a different language from the dropdown, rewrite your logic in the new language, and test thoroughly before saving. The system will show a usage modal to help you understand the impact on existing implementations.
  </Accordion>

  <Accordion title="Where can you reference reusable functions?">
    Reusable functions can be referenced in two contexts:

    * **Business Rule actions** within process nodes
    * **Other reusable functions** to create composite logic
  </Accordion>

  <Accordion title="How do you reference a function?">
    Use the format: `functions.projectName.functionName(input.params)`

    Example: `functions.library1.calculateAgeFromSSN(input.client.ssn)`

    Where:

    * `functions` - Convention to reference a function
    * `library1` - Name of the project/library where the function is defined
    * `calculateAgeFromSSN` - Name of the reusable function
    * `input.client.ssn` - Input parameters using local process variables
  </Accordion>

  <Accordion title="Can you use functions within functions?">
    Yes, you can use functions within functions to create composite business logic. Simply reference other functions using the standard syntax: `functions.projectName.functionName(parameters)` within your function script.
  </Accordion>

  <Accordion title="What data types can you use as parameters?">
    You can use both primitive and object data types as parameters for input and output:

    **Primitive types**: string, number, boolean
    **Object types**: Complex structures with nested properties, arrays, and custom business objects

    Functions automatically handle the data format based on your model definition.
  </Accordion>
</AccordionGroup>


# Reusable UI Templates
Source: https://docs.flowx.ai/5.9/docs/building-blocks/reusable-resources/reusable-ui

Create and manage modular UI components that can be used across multiple User Tasks and processes in your FlowX.AI applications.

## What are Reusable UI Templates?

Reusable UI Templates are self-contained UI component hierarchies that you design once and instantiate multiple times throughout your application. They solve common UI development challenges:

* **Repetitive styling**: No more redoing component styles and properties for similar UI patterns
* **Manual updates**: Reduce the need to manually change components across multiple locations
* **Template management**: Centralized configuration and management of UI templates

<Frame>
  ![Reusable UI Templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/reusable_ui.png)
</Frame>

<Note>
  Reusable UI Templates focus on visual components and layout. They cannot include reusable business rules or complex business logic.
</Note>

## Key benefits

<CardGroup>
  <Card title="Consistency" icon="shield-check">
    Ensure uniform UI patterns across your entire application
  </Card>

  <Card title="Efficiency" icon="clock">
    Design once and use many times - no more recreating similar patterns
  </Card>

  <Card title="Maintainability" icon="wrench">
    Update templates in one place to affect all instances automatically
  </Card>

  <Card title="Omnichannel support" icon="devices">
    Templates work across different platforms and channels
  </Card>
</CardGroup>

## Template types

FlowX.AI supports two main types of reusable UI templates:

<Tabs>
  <Tab title="Dynamic Templates (with inputs)">
    **Characteristics:**

    * Include input parameters that receive data from the process
    * Support output parameters that send data back to the process
    * Contextualized based on runtime data
    * Ideal for forms and data-driven interfaces

    **Use cases:** User registration forms, data collection cards, feedback forms
  </Tab>

  <Tab title="Static Templates (without inputs)">
    **Characteristics:**

    * Self-contained UI components
    * No data exchange with the process
    * Focus on consistent styling and layout
    * Purely visual/structural elements

    **Use cases:** Headers, footers, information panels, navigation elements
  </Tab>
</Tabs>

## Template structure

A reusable template consists of:

* **Root component**: A single container (Card, Container, or Custom Component)
* **UI hierarchy**: Child components arranged in a hierarchical structure
* **Event handlers**: Interactive elements that can trigger process actions
* **Data model**: Input and output parameters for template configuration
* **Configuration**: Name, description, and resource metadata

<Frame>
  ![Reusable UI Template Structure](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/reusable_ui1.png)
</Frame>

## Before you begin

Make sure you have:

* Access to FlowX.AI Designer
* Appropriate permissions to create and manage reusable resources
* A clear understanding of the UI pattern you want to standardize

## Create a reusable template

<Steps>
  <Step title="Access template management">
    1. In FlowX.AI Designer, go to your project
    2. Navigate to **Reusable Resources** > **Templates**
    3. Click **+ New Reusable Template**
  </Step>

  <Step title="Configure basic settings">
    1. Enter a descriptive name for your template (required)

       <Warning>
         Template names cannot contain spaces. Use UpperCamelCase or underscores instead.
       </Warning>

       * ✅ Good: `PersonalDetailsCard`, `User_Registration_Form`
       * ❌ Avoid: `Personal Details Card`, `user-form`

    <Frame>
      ![Personal Details Card](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/personalDetailsCard.png)
    </Frame>

    2. Add an optional description explaining the template's purpose
    3. Choose your root component type:
       * **Card**: Best for content needing visual separation and styling
       * **Container**: Ideal for layout and grouping without visual styling
    4. Configure the data model with input and output parameters
  </Step>

  <Step title="Define the data model">
    The **template data model** defines the internal data structure that the template uses to exchange data with the process — which fields the template receives as input and which it sends back as output. It is separate from the process data model and scoped only to this template.

    <Info>
      If you're unfamiliar with how data models work in FlowX, see the [Process data model](../process/data-model) documentation.
    </Info>

    Set up the internal data structure that your template will use:

    1. **Set the root element** (e.g., `applicationUI`)
    2. **Define field attributes** with appropriate data types:

    **Example: Personal Details Template**

    ```
    applicationUI:
    ├── firstName_UI – string
    ├── lastName_UI – string  
    ├── emailAddress_UI – string
    ├── phoneNumber_UI – string
    ├── dob_UI – date
    ├── gender_UI – string
    ├── consent_UI – boolean
    └── ssn – string
    ```

    <Tip>
      Use descriptive field names with consistent naming patterns (e.g., `fieldName_UI`) to clearly identify template-specific data.
    </Tip>
  </Step>

  <Step title="Configure input and output parameters">
    Define the data contract between your template and the process:

    **Input Parameters:**

    * Data that flows INTO the template from the process
    * Example: `ssn` (pre-filled from existing process data)

    **Output Parameters:**

    * Data that flows OUT of the template back to the process
    * Example: `firstName_UI`, `lastName_UI`, `emailAddress_UI`, `phoneNumber_UI`, `dob_UI`, `gender_UI`, `consent_UI`

    <Info>
      Parameters control data flow only. They don't determine field visibility or editability - you can still edit input parameter fields unless explicitly made read-only.
    </Info>

    Once parameters are defined, click **Done** to establish the template's data contract.
  </Step>

  <Step title="Design the UI hierarchy">
    Use the template UI designer to build your component structure:

    ```
    Root Component (Card/Container)
    ├── UI Components (Text, Input, Button, etc.)
    ├── Layout Components (Containers, Flex containers)
    └── Interactive Components (Forms, Actions)
    ```

    <Info>
      The template UI designer focuses on screen parts without navigation concepts or process-related navigation.
    </Info>
  </Step>

  <Step title="Configure event handlers (optional)">
    Define interactive elements within your template:

    <Tabs>
      <Tab title="Template-defined actions">
        * Define event handlers within the reusable template
        * Assign node actions when instantiated in User Tasks
        * Use for standard actions like "Save", "Submit", or "Cancel"
      </Tab>

      <Tab title="Form-centric actions">
        * Template holds forms with specific information
        * User Task contains actions to validate and send data
        * Use for complex forms combining template and User Task data
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test your template">
    1. Use **Preview Mode** to see how your template renders
    2. Verify component hierarchy and basic functionality
    3. Test with different themes and configurations
    4. Save your template when testing is successful

    <Note>
      Preview Mode provides visual-only testing. Templates are not functional until embedded in a live process with proper parameter mapping.
    </Note>
  </Step>
</Steps>

## Use templates in User Tasks

To integrate reusable templates into your processes, follow this complete workflow:

### Prerequisites: Set up data models

<Steps>
  <Step title="Configure Project Data Model">
    1. In your project, define the main entity (e.g., `Application`)
    2. Add child objects that match your template structure (e.g., `Client`)
    3. Include all fields from your template's data model:
       * `firstName`, `lastName`, `emailAddress`
       * `phoneNumber`, `dob`, `gender`, `consent`, `ssn`
  </Step>

  <Step title="Configure Process Data Model">
    1. Reference the project entity in your process
    2. Select `application` as the root entity
    3. Include `Client` as a child object
    4. The data model will automatically populate with the correct entities
  </Step>
</Steps>

### Add and configure templates

<Steps>
  <Step title="Add template to User Task">
    1. Open the UI Designer for your User Task
    2. In the component panel, locate **Reusable Templates**
    3. Drag and drop your desired template into the UI hierarchy
    4. The template will appear with red warning icons indicating unmapped parameters
  </Step>

  <Step title="Map input parameters">
    1. Select the template instance in the UI hierarchy
    2. Navigate to the template settings panel
    3. Click **Define Parameters** for Input Parameters
    4. Map each input to process data using dynamic keys:

       **Example mapping:**

       ```
       Static value: "123-45-6789"
       Dynamic key: ${application.client.ssn}
       ```

       <Tip>
         Use dynamic keys like `${application.client.fieldName}` to pull data from your process context automatically.
       </Tip>
  </Step>

  <Step title="Map output parameters">
    1. Click **Define Parameters** for Output Parameters

    2. Select all fields that should return data to the process

    3. Map each output to the corresponding process data structure:

       **Example mappings:**

       ```
       applicationUI.firstName_UI → ${application.client.firstName}
       applicationUI.lastName_UI → ${application.client.lastName}
       applicationUI.emailAddress_UI → ${application.client.emailAddress}
       ```

    4. Test the parameter mappings to ensure data flows correctly
  </Step>

  <Step title="Connect template actions to process">
    1. **Define process action**: In Process Designer, create a node action (e.g., `saveData`)
    2. **Link to template**: Return to UI Designer, select the action button within the template
    3. **Configure the handler**: In the **Event Handlers** section, add a handler with **Node Action** as the action type and select your node action
    4. FlowX.AI automatically fills in the action identifier and establishes the connection
  </Step>
</Steps>

### Runtime behavior

At runtime, the process engine expands reusable templates by:

* Replacing the `REUSABLE_TEMPLATE` placeholder with the actual component hierarchy
* Maintaining proper parent-child relationships
* Ensuring unique identifiers for each instance
* Preserving configured event handlers and data bindings

## Manage templates

### View template usage

To see where a template is used:

1. Go to **Reusable Resources** > **Templates**
2. Select your template
3. Click the **Usages** tab
4. Review all processes and User Tasks using the template

### Update templates

When you modify a reusable template:

* Changes automatically propagate to all instances
* Existing process instances may need to restart for updates
* Instance-specific configurations are preserved
* The system validates changes to prevent breaking existing implementations

<Warning>
  Template updates affect all instances immediately. Test changes thoroughly before saving to avoid disrupting active processes.
</Warning>

### Template dependencies

Reusable templates can reference these project resources:

<AccordionGroup>
  <Accordion title="Enumerations">
    Use for dropdown menus and selection components within your templates
  </Accordion>

  <Accordion title="Media items">
    Include images, documents, and other media assets in your templates
  </Accordion>

  <Accordion title="Substitution tags">
    Add dynamic content that updates based on process context
  </Accordion>

  <Accordion title="Themes">
    Apply consistent styling across all template instances
  </Accordion>
</AccordionGroup>

## Event handlers in templates

### Current capabilities

Event handlers in reusable templates support basic interactive functionality. The system handles:

* **Action context management**: Unique identification for template instances
* **Form submission**: Automatic identification of form elements within template context
* **Data mapping**: Proper mapping of data keys to process variables
* **Validation preservation**: Template validation rules are maintained across instances

### Planned scenarios

<Tabs>
  <Tab title="Template-defined actions">
    **How it works:**

    1. Define an event handler within the reusable template
    2. Assign the node action when instantiated in a User Task
    3. Use for standard actions needing different backend connections

    **Best for:** "Save", "Submit", or "Cancel" actions that need process-specific handling
  </Tab>

  <Tab title="Form-centric actions">
    **How it works:**

    1. Template holds a form with additional information
    2. User Task contains the action to validate and send data
    3. Combines data from both template and other User Task forms

    **Best for:** Complex forms where template data combines with User Task data
  </Tab>
</Tabs>

<Info>
  Reusable UI Templates are designed as self-contained components and do not support nesting within other reusable templates
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Template not displaying">
    **Possible causes:**

    * Invalid template hierarchy
    * Missing dependencies (enumerations, media, themes)
    * Insufficient permissions
    * Invalid component configurations

    **Solutions:**

    * Verify template structure in the designer
    * Check all referenced resources exist
    * Confirm user permissions for template access
    * Validate component property settings
  </Accordion>

  <Accordion title="Event handlers not working">
    **Possible causes:**

    * Incorrect action context configuration
    * Invalid form submission setup
    * Data model compatibility issues
    * Missing action permissions

    **Solutions:**

    * Verify action context is properly set
    * Check form submission configuration
    * Ensure data models match between template and process
    * Review user permissions for action execution
  </Accordion>

  <Accordion title="Data binding issues">
    **Possible causes:**

    * Invalid key mappings in template instances
    * Mismatched process data model structure
    * Data type incompatibilities
    * Incorrect substitution tag usage

    **Solutions:**

    * Validate key mappings match expected data structure
    * Check process data model compatibility
    * Ensure data types align between components and data sources
    * Review substitution tag configurations
  </Accordion>
</AccordionGroup>

## Reusable UI Templates vs. Reusable Functions

Understanding the difference between these two reusable components is crucial:

<Tabs>
  <Tab title="Reusable UI Templates">
    **Purpose:** UI Designer components for creating reusable interface elements

    **Scope:**

    * Visual components and layout
    * Styling and basic UI interactions
    * Form structure and input patterns

    **Usage context:** User Tasks and interface design

    **Cannot:** Include reusable business rules or complex business logic
  </Tab>

  <Tab title="Reusable Functions">
    **Purpose:** Business logic components for data processing

    **Scope:**

    * Data processing and validation
    * Calculations and transformations
    * Integration patterns and API calls

    **Usage context:** Service Tasks and process automation

    **Cannot:** Be used within reusable UI templates
  </Tab>
</Tabs>

## Advanced features

### Planned enhancements

<CardGroup>
  <Card title="Template nesting" icon="layer-group">
    Future support for using templates within other templates for enhanced modularity
  </Card>

  <Card title="Enhanced data model" icon="database">
    Input and output parameters with function-like behavior and type safety
  </Card>

  <Card title="Advanced testing" icon="flask">
    Mock data testing and interactive validation capabilities
  </Card>

  <Card title="Cross-project sharing" icon="share">
    Export/import templates and library dependency management
  </Card>
</CardGroup>

### Export and import

You can export and import reusable UI templates to transfer them between projects or environments.

#### Exporting

1. Navigate to **Reusable Resources** > **UI Templates**
2. Open the context menu for the template you want to export
3. Select **Export**
4. The template is downloaded as a ZIP file

#### Importing

1. Navigate to **Reusable Resources** > **UI Templates**
2. Open the context menu and select **Import**
3. Select the ZIP file exported from another project or environment
4. If templates with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting template (or use **Apply to all**):
   * **Keep both** - imports the template as a new copy alongside the existing one
   * **Replace** - overwrites the existing template with the imported version
   * **Skip this one** - keeps the existing template unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>


# Supported scripts
Source: https://docs.flowx.ai/5.9/docs/building-blocks/supported-scripts

Scripts are used to execute actions and configure properties inside nodes. The following script languages are supported.

## Business rules scripting

<CardGroup>
  <Card title="Python 3" icon="python" href="#python-3" />

  <Card title="MVEL" icon="code" href="#mvel" />

  <Card title="Groovy" icon="code" href="#groovy" />

  <Card title="JavaScript" icon="js" href="#javascript" />
</CardGroup>

| Scripting Language | Language Version | Default Engine (5.9.0+)                      | Opt-in Engine             |
| ------------------ | ---------------- | -------------------------------------------- | ------------------------- |
| JavaScript         | ECMAScript 2023  | Node.js V8 (subprocess pool)                 | GraalJS on GraalVM 24.1.2 |
| Python 3           | 3.11             | CPython (subprocess pool)                    | GraalPy on GraalVM 24.1.2 |
| MVEL               | 2                | `org.mvel » mvel2` 2.5.2.Final               | —                         |
| Groovy             | 3.0.21           | `org.codehaus.groovy » groovy-jsr223` 3.0.21 | —                         |

<Info>
  **Starting with 5.9.0, JavaScript and Python execute on a native subprocess pool by default.** Existing scripts that read from `input`, write to `output`, and use language built-ins keep working. `output.put(...)`, `output.get(...)`, and bracket assignment are preserved. To keep the previous GraalVM engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer`. See [Script runtime change](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit.
</Info>

<Info>
  In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.
</Info>

<Warning>
  Python 2.7 is no longer supported. Migrate Python scripts to Python 3 to take advantage of improved performance and modern language features.
</Warning>

## Integration designer scripting

| Scripting Language | Language Version | Default Engine (5.9.0+)      | Opt-in Engine             |
| ------------------ | ---------------- | ---------------------------- | ------------------------- |
| JavaScript         | ECMAScript 2023  | Node.js V8 (subprocess pool) | GraalJS on GraalVM 24.1.2 |
| Python             | 3.11             | CPython (subprocess pool)    | GraalPy on GraalVM 24.1.2 |

***

## Input and output

Scripts in FlowX receive data through bound variables. The available variables depend on the context.

### Available variables

| Variable           | Type                   | Process business rules | Workflow scripts | Description                                                   |
| ------------------ | ---------------------- | ---------------------- | ---------------- | ------------------------------------------------------------- |
| `input`            | `Map` (read-only copy) | ✅                      | ✅                | Process instance data or workflow start node data             |
| `output`           | `Map` (mutable)        | ✅                      | ✅                | Write results here — data is persisted after script execution |
| `additionalData`   | `Map`                  | ✅                      | ✅                | Contains `securityDetails` and `applicationConfiguration`     |
| `instanceMetadata` | `Map`                  | ✅                      | ❌                | Process instance metadata (not available in workflows)        |

### Writing to output

Assign values to the `output` variable to persist data. Both assignment and `.put()` syntax work.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    // Dot notation
    output.clientName = input.firstName + " " + input.lastName;

    // Bracket notation
    output["totalAmount"] = input.price * input.quantity;

    // Java method (also works)
    output.put("status", "approved");

    // Nested objects
    output.address = {
      street: input.streetName,
      city: input.cityName
    };
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Bracket notation
    output["clientName"] = input["firstName"] + " " + input["lastName"]

    # Java method (also works)
    output.put("totalAmount", input["price"] * input["quantity"])

    # Nested objects
    output["address"] = {
      "street": input["streetName"],
      "city": input["cityName"]
    }
    ```
  </Tab>
</Tabs>

### Reading from input

`input` is a deep copy of the process or workflow data. Changes to `input` are not persisted. Always write to `output`.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    // Dot notation
    var name = input.application.client.name;

    // Bracket notation
    var code = input["application"]["countryCode"];

    // Safe access for optional fields
    var detail = input.query?.detail_level || "basic";
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Bracket notation
    name = input["application"]["client"]["name"]

    # Check before accessing optional fields
    if "countryCode" in input["application"]:
        code = input["application"]["countryCode"]
    ```
  </Tab>
</Tabs>

### Accessing configuration parameters

Retrieve project-level configuration parameters through `additionalData`:

```javascript theme={"system"}
var commission = additionalData.applicationConfiguration.get("commissionPercentage");
output.commissionValue = input.amount * commission;
```

For security details and more examples, see [Extracting additional data in business rules](./actions/business-rule-action/extracting-additional-data).

### Common pitfalls

<AccordionGroup>
  <Accordion title="Output is empty ({})">
    If your script runs without errors but output is `{}`:

    * **Check your variable names**. `output` must be spelled exactly, it's case-sensitive
    * **Check assignment syntax**. In Python, use `output["key"] = value` (bracket notation), not `output.key = value`
    * **Don't reassign output**. `output = {"key": "value"}` replaces the reference and won't persist. Use `output["key"] = "value"` instead
    * **Don't use `return`**. Scripts don't need a return statement. Write directly to `output`.
  </Accordion>

  <Accordion title="Python import errors">
    Python scripts run in a sandboxed environment. Common modules like `uuid`, `re`, and other standard library imports are not available.

    ```python theme={"system"}
    # ❌ This will fail
    import uuid
    output["id"] = str(uuid.uuid4())

    # ✅ Use alternative approaches or generate IDs in a different node
    ```
  </Accordion>

  <Accordion title="Python syntax limitations">
    Some Python patterns behave differently in the GraalPy sandbox:

    ```python theme={"system"}
    # ❌ enumerate() not available
    for i, item in enumerate(items):

    # ✅ Use manual index
    i = 0
    while i < len(items):
        item = items[i]
        i = i + 1

    # ❌ .get() with default argument may cause arity errors
    value = input.get("key", "default")

    # ✅ Check key existence first
    if "key" in input:
        value = input["key"]
    else:
        value = "default"

    # ❌ dict.items() iteration not supported
    for k, v in data.items():

    # ✅ Iterate over keys
    keys = list(data.keys())
    i = 0
    while i < len(keys):
        k = keys[i]
        v = data[k]
        i = i + 1
    ```
  </Accordion>

  <Accordion title="Java HashMap interop in JavaScript">
    When accessing data returned by Java services (such as AI node output), values may be Java HashMaps rather than native JavaScript objects. Standard JS methods like `Object.keys()` and spread syntax may not work as expected.

    ```javascript theme={"system"}
    // ❌ May not work with Java HashMaps
    var keys = Object.keys(javaMap);
    var copy = {...javaMap};

    // ✅ Use Java interop
    var value = javaMap.get("key");
    javaMap.put("key", "value");
    ```
  </Accordion>
</AccordionGroup>

### Scripts in Integration Workflows

Script nodes in [Integration Workflows](../platform-deep-dive/integrations/integration-designer) use the same `input` and `output` variables as process business rules, but the data flow is different:

* **In a process business rule**, `output` writes directly to the process instance data store.
* **In a workflow Script node**, `output` becomes the `input` for the **next node** in the workflow. The data stays within the workflow until the workflow completes at an **End** node.

Only the End node output is mapped back to the calling process (via a Receive Message Task with a "From Workflow" data stream).

<Info>
  If your workflow Script node produces an empty `output` (`{}`), subsequent nodes in the workflow receive no data. To pass all input data through to the next node while adding or modifying fields, copy the input to output first:

  ```javascript theme={"system"}
  // Copy all input data to output, then add/modify fields
  output.put("", input);
  output.ticket_id = "TICKET-" + Math.floor(Math.random() * 100000);
  output.timestamp = new Date().toISOString();
  ```

  The `output.put("", input)` call copies all keys from `input` into the root of `output`.
</Info>

For details on mapping workflow output back to your process, see [Workflow data models](../platform-deep-dive/integrations/workflow-data-models).

***

## JavaScript

<Info>
  **New in v4.7.1**: JavaScript support has been upgraded from Nashorn (ECMAScript 5.1) to GraalJS (ECMAScript 15/2024), providing significantly improved performance and modern language features.
</Info>

JavaScript in FlowX.AI is powered by GraalJS, which supports ECMAScript 15 (2024) standards. This provides modern JavaScript capabilities for your business rules and integrations.

### What is GraalJS?

GraalJS is an ECMAScript compliant JavaScript implementation built on GraalVM. It supports the latest ECMAScript features and offers high performance through the GraalVM's JIT compiler.

### Properties

* Supports ECMAScript 15 (2024) features including modern syntax and APIs
* Provides consistent scripting across business rules and integration designer
* Runs in a secure sandboxed environment

### Limitations

JavaScript scripts run in a sandboxed environment. Here is a list of JavaScript features not available in the sandbox:

* import.meta (ES2020)
* top-level await (ES2022)
* set operations (ES2024)
* Array.fromAsync (ES2024)

### Useful links

<Card title="GraalJS Documentation" href="https://www.graalvm.org/javascript/" icon="link" />

<Card title="ECMAScript 2024 Language Specification" href="https://tc39.es/ecma262/" icon="link" />

***

## Python 3

Python is a high-level, interpreted programming language known for its simplicity and readability. FlowX.AI uses Python 3.11.7 via GraalPy for executing Python scripts.

### What is GraalPy?

GraalPy is an implementation of Python that runs on the GraalVM. It offers high compatibility with standard Python (CPython) while providing the ability to run within the Java ecosystem. GraalPy supports Python 3 and provides access to a large subset of the standard Python library.

### Properties

* Supports Python 3.11.7 with access to most common Python libraries
* Runs up to 3x faster than Python 2.7 via Jython
* Runs in a sandboxed environment for better security

### Python Library Support

Python 3 support in FlowX comes with a subset of the [standard Python library](https://docs.python.org/3.11/library/index.html). Python runs in a sandboxed environment and the following modules are not available:

"stringprep", "sqlite3", "plistlib", "getpass", "curses", "curses.textpad", "curses.ascii", "curses.panel", "xml.parsers.expat", "xmlrpc.client", "xmlrpc.server", "turtle", "tkinter", "test.support", "symtable", "pyclbr", "msvcrt", "winreg", "winsound", "grp", "termios", "tty", "pty", "syslog", "audioop", "msilib", "nis", "ossaudiodev", "smtpd", "spwd", "crypt"

<Warning>
  Available modules might provide limited access to system resources due to the execution in a sandbox environment.
</Warning>

### Useful links

<Card title="Python 3.11 Documentation" href="https://docs.python.org/3.11/" icon="link" />

<Card title="GraalPy Documentation" href="https://www.graalvm.org/python/" icon="link" />

## MVEL

MVEL is an expression language for Java-based applications. It provides a plethora of features and is suited for everything from the smallest property binding and extraction, to full-blown scripts.

* FlowX.AI uses [**mvel2 - 2.5.2.Final version**](https://mvnrepository.com/artifact/org.mvel/mvel2/2.5.2.Final)

### Useful links

<Card title="MVEL Documentation" href="http://mvel.documentnode.com/" icon="link" />

<Card title="Maven repository: Mvel 2.5.2 Final" href="https://github.com/mvel/mvel/tags" icon="link" />

***

## Groovy

Groovy is a multi-faceted language for the Java platform. The language can be used to combine Java modules, extend existing Java applications and write new applications

We use and recommend **Groovy 3.0.21** version, using **groovy-jsr223** engine.

<Info>
  **Groovy** has multiple ways of integrating with Java, some of which provide richer options than available with **JSR-223** (e.g. greater configurability and more security control). **JSR-223** is recommended when you need to keep the choice of language used flexible and you don't require integration mechanisms not supported by **JSR-223**.
</Info>

<Info>
  **JSR-223** (spec) is **a standard scripting API for Java Virtual Machine (JVM) languages** . The JVM languages provide varying levels of support for the JSR-223 API and interoperability with the Java runtime.
</Info>

### Useful links

<Card title="Groovy Language Documentation" href="https://docs.groovy-lang.org/docs/groovy-3.0.21/html/documentation/" icon="link" />

<Card title="[Java] Class GroovyScriptEngineImpl" href="https://docs.groovy-lang.org/latest/html/gapi/org/codehaus/groovy/jsr223/GroovyScriptEngineImpl.html" icon="link" />

<Card title="groovy-jsr223" href="https://mvnrepository.com/artifact/org.codehaus.groovy/groovy-jsr223" icon="link" />

***

## Academy courses

<CardGroup>
  <Card title="Exclusive Gateways course" icon="graduation-cap" href="https://academy.flowx.ai/explore/configure-exclusive-gateways">
    Learn to configure conditions in JavaScript and DMN for gateway routing
  </Card>

  <Card title="Debug 101 course" icon="graduation-cap" href="https://academy.flowx.ai/explore/debug-your-process-0">
    Troubleshoot script execution errors, exceptions, and debugging patterns
  </Card>
</CardGroup>

<Tip>
  **Academy playground**. Explore the [**Academy\_ExclusiveGateways**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/173d95f6-a1ee-447a-853c-3edee11b75b1/config/2a6fc79d-f993-4114-94d8-771104ffb650/processes) project for working examples of JavaScript and DMN conditions in gateway routing.
</Tip>


# Token
Source: https://docs.flowx.ai/5.9/docs/building-blocks/token

Token represents the current position in the process flow. When you start a process, you have a graph of nodes that connect based on the defined sequence and configuration.

The token is a [BPMN](../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn) concept that represents a state within a process instance. It keeps track of the current position in the process flow and is used to store data related to the current process instance state.

A token is created each time a new process instance starts. As actions on the process instance execute, the token advances from one node to the next. Because a node can have several [actions](./actions/actions) that need execution, the token also tracks the actions executed in each node.

<Tip>
  For [parallel gateways](./node/parallel-gateway), child tokens are created for each flow branch. The parent token moves to the gateway sync node and advances only after all child tokens reach that node.
</Tip>

The following diagram shows how a token advances through a process flow:

<Frame title="Token flow diagram">
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/flowx-token-flow-diagram.svg)
</Frame>

The token moves to the next node only after all mandatory actions from the current node are executed. The token also waits on a node if the node is configured to receive an event from an external system through Kafka.

<Tip>
  Sometimes the token stops at a node until user input is received. If user input is required to advance the process, the token advances only after all data is received. Use a mandatory manual action linked to the user action to ensure the process flow advances only after the user input is received.
</Tip>

## Viewing tokens

Retrieve the current process instance status using the FlowX Designer. The Designer displays information about tokens related to that process instance and the current nodes they are in.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token_view.png)

### Token view table

The token view displays tokens in a **tree table** format, providing a hierarchical view of parent and child tokens. This format is especially useful when working with parallel gateways or embedded subprocesses.

<Info>
  If parallel gateways are configured in a process, multiple tokens are created, one for each parallel path.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/parallel_tokens.png)
</Info>

#### Token view features

<CardGroup>
  <Card title="Tree structure" icon="sitemap">
    Tokens are displayed hierarchically, showing parent-child relationships. All rows are expanded by default.
  </Card>

  <Card title="Horizontal scrolling" icon="arrows-left-right">
    The table supports horizontal scrolling to accommodate all columns
  </Card>

  <Card title="Frozen columns" icon="grip-vertical">
    The UUID and Token Status columns remain fixed when scrolling horizontally for constant visibility
  </Card>

  <Card title="Tooltips" icon="info">
    Long names are truncated with tooltips showing the full text on hover
  </Card>
</CardGroup>

The token view table includes the following columns:

| Column                  | Description                                                                                                                                                                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **UUID**                | Unique identifier for the token. Only the first 6 characters are displayed with a copy icon. Clicking the icon copies the full UUID to clipboard. **Frozen column** (stays visible during horizontal scroll)                                   |
| **Token Status**        | Current state of the token in the process (ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, or TERMINATED). Displayed as color-coded tags. **Frozen column** (stays visible during horizontal scroll)                                   |
| **Context**             | Shows the main process name for tokens in the main process, or the embedded subprocess name for tokens running within embedded subprocesses (any nesting level)                                                                                |
| **Initiator Node**      | The node or event that initiated the token (for example, Parallel Gateway, Non-interrupting boundary event). Applies to child tokens only; displays "-" for parent tokens                                                                      |
| **First Executed Node** | The node where the token first executed. For parallel gateway tokens, shows the first executed node on that parallel branch. For boundary event tokens, shows the first executed node on the branch started from the boundary node             |
| **Current Node**        | The node where the token is currently positioned. For tokens in embedded subprocesses, displays the current node from the subprocess                                                                                                           |
| **Current Node Status** | The token's status within the current node (ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL, WAITING\_MESSAGE\_EVENT, WAITING\_TIMER\_EVENT, WAITING\_MESSAGE, MESSAGE\_RECEIVED, or MESSAGE\_RESPONSE\_TIMED\_OUT). Sortable column |
| **Last updated**        | The date and time when the token was last updated. Displays full datetime in browser timezone                                                                                                                                                  |
| **Actions**             | Available actions including Retry (only visible for ACTIVE tokens) and View details (eye icon)                                                                                                                                                 |

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token_status_cn.png)
</Frame>

## Understanding token status

### Token status values

The token status indicates the lifecycle state of a token in the process:

<AccordionGroup>
  <Accordion title="ACTIVE" icon="circle-check">
    Token state is active when tokens are created. A parent token reactivates when all child tokens reach the parallel gateway closing node.
  </Accordion>

  <Accordion title="INACTIVE" icon="circle-pause">
    Child tokens become inactive when they arrive at a parallel gateway closing node. The current token becomes inactive when it reaches a final node.
  </Accordion>

  <Accordion title="ABORTED" icon="circle-xmark">
    The current token becomes aborted when it moves backward to redo a series of previous actions in the process. The token resets, and a new token activates.
  </Accordion>

  <Accordion title="ON HOLD" icon="circle-pause">
    When a parallel split gateway node is reached, the parent token is set to On hold until all child tokens reach the parallel gateway closing node. The parent token does not have a "Retry" action icon until all child tokens finish.
  </Accordion>

  <Accordion title="DISMISSED" icon="circle-minus">
    The process or subprocess reaches a certain node and is canceled or exited.
  </Accordion>

  <Accordion title="EXPIRED" icon="clock">
    A defined "expiryTime" in the process definition passes, and the token changes to this status.
  </Accordion>

  <Accordion title="TERMINATED" icon="ban">
    The process is terminated by a termination request.
  </Accordion>
</AccordionGroup>

### Current node status values

The current node status indicates the execution status of the token within its current node:

<AccordionGroup>
  <Accordion title="ARRIVED" icon="location-dot">
    The token reaches a new node
  </Accordion>

  <Accordion title="EXECUTING" icon="play">
    The token execution starts
  </Accordion>

  <Accordion title="EXECUTED_COMPLETE" icon="circle-check">
    Node actions execute, and all mandatory actions from the node complete
  </Accordion>

  <Accordion title="EXECUTED_PARTIAL" icon="circle-half-stroke">
    Node actions execute, but mandatory uncompleted actions remain
  </Accordion>

  <Accordion title="WAITING_MESSAGE_EVENT" icon="envelope">
    The token reaches an intermediate message catch event node
  </Accordion>

  <Accordion title="WAITING_TIMER_EVENT" icon="clock">
    The token reaches an intermediate timer event node
  </Accordion>

  <Accordion title="WAITING_MESSAGE" icon="hourglass-half">
    The token waits for a message from another system
  </Accordion>

  <Accordion title="MESSAGE_RECEIVED" icon="check">
    The message is received
  </Accordion>

  <Accordion title="MESSAGE_RESPONSE_TIMED_OUT" icon="triangle-exclamation">
    The message is not received within the set timeframe
  </Accordion>
</AccordionGroup>

### Initiator types

Tokens can be initiated by different sources. The initiator information is displayed in the **Initiator Node** column of the token view:

<CardGroup>
  <Card title="START_EVENT" icon="play">
    Token initiated by a process start event. Parent tokens display "-" in the Initiator Node column.
  </Card>

  <Card title="BOUNDARY_EVENT" icon="clock">
    Token initiated by a boundary event (for example, timer or message boundary event). The boundary event node name is displayed in the Initiator Node column.
  </Card>

  <Card title="PARALLEL_GATEWAY" icon="code-branch">
    Child token created by a parallel split gateway. The parallel gateway node name is displayed in the Initiator Node column.
  </Card>

  <Card title="SUBPROCESS" icon="layer-group">
    Token created for an embedded subprocess execution.
  </Card>
</CardGroup>

<Info>
  For tokens initiated by a **BOUNDARY\_EVENT** within an embedded subprocess, the token context is preserved and the initiator node name is correctly mapped in the token view.
</Info>

### Viewing token details

To view more details about a token:

<Steps>
  <Step title="Open Process status">
    Click the **Process status** view button in the FlowX Designer.
  </Step>

  <Step title="Select a token">
    Select a token from the token list.
  </Step>

  <Step title="View details">
    Click the **view button** (eye icon) to open the detailed token status view.
  </Step>
</Steps>

Access the detailed token status view by navigating to Process instance → Tokens → View (eye icon). The detailed token status modal displays comprehensive information about the token's current state, execution history, and configuration in a structured key-value format.

<Frame title="Token status modal">
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token_status.png)
</Frame>

The detailed token status view presents token information in an expandable JSON-like structure. Key identifiers and status values are highlighted for quick identification. The modal includes the following fields organized by category:

<AccordionGroup>
  <Accordion title="Token identification" icon="fingerprint">
    * **id**: The unique identifier of the token
    * **version**: The version number of the token schema
    * **parentTokenId**: The identifier of the parent token (present for child tokens created by parallel gateways or subprocesses)
    * **processInstanceId**: The identifier of the process instance this token belongs to
  </Accordion>

  <Accordion title="Token state" icon="circle-info">
    * **state**: The current lifecycle state of the token (see [Token status values](#token-status-values) for details)
    * **statusCurrentNode**: The execution status of the token within its current node (see [Current node status values](#current-node-status-values) for details)
    * **dateUpdated**: The ISO 8601 timestamp indicating when the token was last updated
  </Accordion>

  <Accordion title="Node information" icon="diagram-project">
    * **startNodeId**: The identifier of the node where the token execution began
    * **currentNodeId**: The identifier of the node where the token is currently positioned
    * **currentNodeName**: The human-readable name of the current node
    * **currentNode**: Detailed information about the current node object
    * **embedNodeId**: The identifier of the embedded node, if the token is executing within an embedded subprocess
    * **mainSwimlaneId**: The identifier of the main swimlane associated with the token
  </Accordion>

  <Accordion title="Process context" icon="sitemap">
    * **currentProcessVersionId**: The identifier of the process version currently being executed
    * **currentContext**: The current execution context (typically "main" for the main process, or the subprocess name for embedded subprocesses). This corresponds to the **Context** column in the token view table.
  </Accordion>

  <Accordion title="Initiator information" icon="play">
    * **initiatorType**: The type of initiator that created this token (see [Initiator types](#initiator-types) for details)
    * **initiatorId**: The identifier of the initiator node or event
    * **initiatorNode**: The name of the node that initiated the token. This corresponds to the **Initiator Node** column in the token view table.
  </Accordion>

  <Accordion title="Synchronization" icon="sync">
    * **syncNodeTokensCount**: The total number of synchronized node tokens (used for parallel gateway synchronization)
    * **syncNodeTokensFinished**: The count of synchronized node tokens that have finished execution
  </Accordion>

  <Accordion title="Execution history" icon="history">
    * **nodesActionStates**: An expandable array containing detailed information about the action states for each node the token has visited. Each entry includes:
      * **nodeId**: The identifier of the node
      * **context**: The execution context (main or subprocess name)
      * **embedNodeId**: The embedded node identifier, if applicable
      * **name**: The name of the node
    * **backSeq**: An expandable object containing backward sequence information for tokens that have moved backward in the process flow:
      * **nodesSeq**: An array of node sequences that were executed in reverse order
      * **uuid**: The unique identifier for the backward sequence
      * **context**: The context where the backward sequence occurred
      * **initiatorNode**: The name of the node that initiated the backward sequence
      * **firstExecutedNode**: The first node executed in the backward sequence
      * **currentNode**: The current node in the backward sequence
  </Accordion>

  <Accordion title="Additional data" icon="database">
    * **paramValues**: Parameter values and process variables associated with the token
  </Accordion>
</AccordionGroup>

<Info>
  The **nodesActionStates** and **backSeq** sections are expandable in the detailed token status view. Expand these sections to view comprehensive information about node execution history and backward sequence tracking.
</Info>


# Conditional styling
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/conditional-styling

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

Conditional styling enables dynamic, data-driven design adjustments based on specific conditions. It helps reduce the need for multiple prototypes by applying styles conditionally, depending on the data and platform-specific configurations.

<Info>
  **Conflict Resolution:** When multiple conditions overlap, the latest condition (evaluated from top-to-bottom) takes priority.
</Info>

***

## Configuring conditional styling

1. Open the **UI Designer**.
2. Select a **Text**, **Link**, or **Container** element.
3. Navigate to the **Styles** tab.
4. Locate the **Conditional Styling** section.
5. Click the **➕** icon to add new expressions and effects.
6. Use the **JS Editor** to configure and test your expressions for accurate behavior.

***

## Conditional styling properties

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)
</Frame>

<Info>
  **Availability:** Conditional styling is available for **Text**, **Link**, and **Container** UI elements.
</Info>

***

## Structure of conditional styling

1. **Condition:**
   * A string expression evaluated similarly to hide/disable expressions.
   * Supports referencing process data store keys for dynamic evaluations.

2. **Overrides:**
   * A key-value map defining specific property-value pairs.
   * Overrides are applied based on the evaluated condition.

### Example:

```json theme={"system"}
{
  "platformDisplayOptions": {
    "platform": "web",
    "style": {
      "conditionals": [
        {
          "condition": "$user.age > 30",
          "overrides": {
            "backgroundColor": "#FFD700",
            "fontWeight": "bold"
          }
        },
        {
          "condition": "$user.subscription == 'premium'",
          "overrides": {
            "borderColor": "#4CAF50",
            "textColor": "#FFFFFF"
          }
        }
      ]
    }
  }
}
```

## Renderer behavior

* **Real-Time Evaluation**: Conditions are continuously evaluated based on live data updates.
* **Priority Handling**: If multiple conditions are met, the last condition in the sequence takes precedence.
* **Dynamic Application**: Styles are applied instantly upon condition satisfaction, enhancing UI responsiveness.

## Contextual menu options

* Conditional Styling Section: Copy To/From Platforms to reuse conditions across different environments.
* Expression + Effect Section: Copy To/From Platforms and Delete options for efficient management.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/contextual_menu.png)
</Frame>

## Key notes

* **Dynamic Styling**: Facilitates platform-specific style overrides driven by real-time data conditions.
* **Scalability**: Designed to support iterative and scalable UI implementations.
* **Enhanced Usability**: Simplifies user interaction with intuitive UI/UX components, making style management more accessible and efficient.

<Tip>
  Combine conditional styling with data-driven expressions to create responsive, adaptable UI designs effortlessly.
</Tip>


# Dynamic & computed values
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/dynamic-and-computed-values

Build dynamic, interactive UIs with dynamic and computed values that deliver personalized and responsive experiences to users.

## Dynamic values

Dynamic values give you the flexibility to fill various UI properties at runtime, based on process parameters or substitution tags. By doing so, your application can adapt to specific scenarios or user inputs.

Use this feature to fine-tune how your application appears and behaves without needing to rebuild or redeploy. The table below outlines which UI elements support dynamic values and the corresponding properties that can accept parameters or substitution tags.

| **Element**                                                                                                                                            | **Properties**                                                                                                                         | **Accepts**                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [**Form Elements**](./ui-component-types/form-elements)<br /> *Input, Textarea, Select, Checkbox, Radio, Switch, Datepicker, Slider, Segmented Button* | - **Default Value**<br />- **Label**<br />- **Placeholder**<br />- **Helper Text**<br />- **Validators**<br />- **Prefix**, **Suffix** | **Yes:** Process parameters or Substitution tags |
| [**File Preview**](./ui-component-types/file-preview)                                                                                                  | - **Title**<br />- **Subtitle**                                                                                                        | **Yes:** Process parameters or Substitution tags |
| [**Card**](./ui-component-types/root-components/card)                                                                                                  | - **Title**<br />- **Subtitle**                                                                                                        | **Yes:** Process parameters or Substitution tags |
| **Form**                                                                                                                                               | - **Title**                                                                                                                            | **Yes:** Process parameters or Substitution tags |
| **Message**                                                                                                                                            | - **Message**                                                                                                                          | **Yes:** Process parameters or Substitution tags |
| [**Button**](./ui-component-types/buttons), [**Upload**](./ui-component-types/buttons)                                                                 | - **Label**                                                                                                                            | **Yes:** Process parameters or Substitution tags |
| **Select**, **Checkbox**, **Radio**, **Segmented Button**<br />(*Static source type only*)                                                             | - **Label**<br />- **Value**                                                                                                           | **Substitution tags only**                       |
| **Text**                                                                                                                                               | - **Text**                                                                                                                             | **Yes:** Process parameters or Substitution tags |
| **Link**                                                                                                                                               | - **Link Text**                                                                                                                        | **Yes:** Process parameters or Substitution tags |
| **Modal** <br />*(`modalDismissAlert` properties)*                                                                                                     | - **Title**<br />- **Message**<br />- **ConfirmLabel**<br />- **CancelLabel**                                                          | **Yes:** Process parameters or Substitution tags |
| **Step**                                                                                                                                               | - **Label**                                                                                                                            | **Yes:** Process parameters or Substitution tags |
| **Tab**                                                                                                                                                | - **Title**                                                                                                                            | **Yes:** Process parameters or Substitution tags |

<Info>
  Default Value is not available for the **Switch** element.
</Info>

### How it works

* **Process Parameters**: At runtime, values can be injected from backend logic or state, such as the outcome of an API call or an action, which then populate the relevant UI element properties.
* **Substitution Tags**: Whenever a UI property references a substitution tag key (e.g., `test`), the application replaces it with the appropriate content at runtime. This is particularly useful for rapid localization, real-time data injection, and user-specific content.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-16%20at%2014.10.36.png)
</Frame>

### Example using Substitution tags

<Tip>
  Use keys beginning with "@@" to return their value. If a valid key isn't found, you'll get an empty string. If the key format is incorrect, the original string is returned.
</Tip>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release-notes/dynamic_val.gif)

### Example using process parameters

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/dynamic_values_params.gif)

#### Business rule example

In the preceding example, an MVEL business rule demonstrates the population of specific keys with dynamic values from the task. This JSON object, assigned to the "app" key, captures the values for various UI properties:

```json theme={"system"}
///assigning a JSON object containing dynamic values for the specified keys to the "app" key 

output.put("app",{"label":"This is a label",
                    "title":"This is a title",
                    "placeholder":"This is a placeholder",
                    "helpertext":"This is a helper text",
                    "errorM":"This is a error message",
                    "prefix":"prx",
                    "suffix":"sfx",
                    "subtitile":"This is a subtitle",
                    "message":"This is a message",
                    "defaultV":"defaultValue",
                    "value":"Value101",
                    "value":"Value101",
                    "confirmLabel":"This is a confirm label",
                    "cancelLabel":"This is a cancel label",
                    "defaultValue":"dfs",
                    "defaultDate":"02.02.2025",
                    "defaultSlider": 90});

```

<Warning>
  Note that for releases **\< 3.3.0**, concatenating process parameters with substitution tags isn't supported when utilizing dynamic values.
</Warning>

## Computed values

Computed values present a method to dynamically generate values using JavaScript expressions. Beyond adhering to predefined values, computed values enable the manipulation, calculation, and transformation of data grounded in particular rules or conditions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/computed1.png)

Computed values can be created via JavaScript expressions that operate on process parameters or other variables within the application.

<Tip>
  To introduce a computed value, toggle the "Computed value" option (represented by the **f(x)** icon). This will transform the chosen field into a JavaScript editor.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/computed_default_value.png)
  </Frame>
</Tip>

By enabling computed values, the application provides flexibility and the ability to create dynamic and responsive user interfaces.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release-notes/computed.gif)

### Slider example (parsing keys as integers)

The instance above showcases computed values' usage in a Slider element. JavaScript expressions are used to dynamically compute minimum and maximum values based on a value sourced from a linked input UI element (connected via the process key `${application.client.amount}`).

#### Minimum Value

```js theme={"system"}
if ( !isNaN(parseInt(${application.client.amount})) ) {
    return 0.15 * parseInt(${application.client.amount})
}  else {
    return 10000
}
```

* `!isNaN(parseInt(${application.client.amount}))`: This part ascertains whether the value in the input field `(${application.client.amount})` can be effectively converted to an integer using `parseInt`. Moreover, it validates that the outcome isn't `NaN` (i.e., not a valid number), ensuring input validity.
* If the input is a valid number, the minimum value for the slider is calculated as 15% of the entered value `(0.15 * parseInt(${application.client.amount}))`.
* If the input is not a valid number `(NaN)`, the minimum value for the slider is set to 10000.

#### Maximum Value

```js theme={"system"}
if ( !isNaN(parseInt(${application.client.amount})) ) {
    return 0.35 * parseInt(${application.client.amount})
}  else {
    return 20000
}
```

* Similar to the previous expression, it checks if the value entered on the input field is a valid number using `!isNaN(parseInt(${application.client.amount}))`.
* If the input is a valid number, the maximum value for the slider is calculated as 35% of the entered value `(0.35 * parseInt(${application.client.amount}))`.
* If the input is not a valid number `(NaN)`, the maximum value for the slider is set to 20000.

#### Summary

In summary, the above expressions provide a dynamic range for the slider based on the value entered on the input field. If a valid numeric value is entered, the slider's range will be dynamically adjusted between 15% and 35% of that value. If the input is not a valid number, a default range of 10000 to 20000 is set for the slider. This can be useful for scenarios where you want the slider's range to be proportional to a user-provided value.

### Text example (using computed strings)

The following scenario outlines the functionality and implementation of dynamically displayed property types via a text UI element. This is done based on the chosen loan type through a select UI element in a user interface.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dynamic_string.gif)

#### Scenario

The UI in focus showcases two primary UI elements:

* Select Element - "Loan type": This element allows users to choose from different loan types, including "Conventional," "FHA," "VA," and "USDA."

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loan_type.png)

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/select_values.png)
</Frame>

* Text Element - "Property type": This element displays property types based on the selected loan type.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/property_type.png)
</Frame>

The following code snippet illustrates how the dynamic property types are generated based on the selected loan type (JavaScript is used):

```javascript theme={"system"}
if ("${application.loanType}" == "conventional") {
    return "Single-Family Home, Townhouse CondoMulti-Family, Dwelling";
} else if ("${application.loanType}" == "fha") {
    return "Single-Family Home, Townhouse, Condo, Manufactured Home";
} else if ("${application.loanType}" == "va") {
    return "Single-Family Home, Townhouse, Condo, Multi-Family Dwelling";
} else if ("${application.loanType}" == "usda") {
    return "Single-Family Home, Rural Property, Farm Property";
} else {
    return "Please select a loan type first";
}
```

#### Summary

* **Loan Type Selection**: Users interact with the "Loan Type Select Element" to choose a loan type, such as "Conventional," "FHA," "VA," or "USDA."
* **Property Types Display**: Once a loan type is selected, the associated property types are dynamically generated and displayed in the "Text Element."
* **Fallback Message**: If no loan type is selected or an invalid loan type is chosen, a fallback message "Please select a loan type first" is displayed.

### Integration across the UI elements

The UI Designer allows the inclusion of JavaScript expressions for generating computed values. This functionality extends to the following UI elements and their associated properties:

| Element                                | Properties                          |
| -------------------------------------- | ----------------------------------- |
| Slider                                 | min Value, max Value, default Value |
| Input                                  | Default Value                       |
| Any UI Element that accepts validators | min, max, minLength, maxLength      |
| Text                                   | Text                                |
| Link                                   | Link Text                           |

* **Slider**: The min value, max value, and default value for sliders can be set using JavaScript expressions applied to process parameters. This allows for dynamic configuration based on numeric values.
* **Any UI Element that accepts validators min, max, minLength, maxLength**: The "params" field for these elements can also accept JavaScript expressions applied to process parameters. This enables flexibility in setting validator parameters dynamically.
* **Default Value**: For input elements like text inputs or number inputs, the default value can be a variable from the process or a computed value determined by JavaScript expressions.
* **Text**: The content of a text element can be set using JavaScript expressions, allowing for dynamic text generation or displaying process-related information.
* **Link**: The link text can also accept JavaScript expressions, enabling dynamic generation of the link text based on process parameters or other conditions.

<Tip>
  When working with computed values, it's important to note that they are designed to be displayed as integers and strings.
</Tip>

<Info>
  For input elements (e.g., text input), you may require a default value from a process variable, while a number input may need a computed value.
</Info>

## Understanding the return statement

### Why the return statement is essential

When working with computed values in the UI Designer, **the `return` statement is mandatory** for your JavaScript expressions to function correctly. This is a fundamental requirement that ensures your computed values are properly evaluated and applied to UI elements.

**Technical Reason**: Computed values are executed as JavaScript functions in the UI Designer's evaluation engine. Like any JavaScript function, they must explicitly return a value to provide output to the calling context.

### The role of return in computed values

Computed values use JavaScript expressions that must explicitly return a value using the `return` statement. Without it, your expression will not produce any output, and the UI element will not receive the expected value.

<Warning>
  **Critical**: If you forget the `return` statement, your computed value will evaluate to `undefined`, which can cause:

  * UI elements to display blank or default values
  * Validation rules to fail unexpectedly
  * Slider ranges to become invalid
  * Text elements to appear empty
</Warning>

#### ✅ Correct Implementation

```javascript theme={"system"}
// Slider minimum value calculation
if (!isNaN(parseInt(${application.client.amount}))) {
    return 0.15 * parseInt(${application.client.amount});
} else {
    return 10000;
}
```

#### ❌ Incorrect Implementation

```javascript theme={"system"}
// This will NOT work - missing return statements
if (!isNaN(parseInt(${application.client.amount}))) {
    0.15 * parseInt(${application.client.amount}); // No return!
} else {
    10000; // No return!
}
```

### Best practices for testing

#### Always include return statements

Every code path in your computed value expression should have a `return` statement.

#### Handle edge cases

```javascript theme={"system"}
// Good practice: Handle both valid and invalid inputs
if (!isNaN(parseInt(${application.client.amount}))) {
    return 0.15 * parseInt(${application.client.amount});
} else {
    return 10000; // Fallback value
}
```

#### Test different scenarios

When testing your computed values, ensure you test:

* **Valid input values** - Normal expected data
* **Invalid or empty input values** - `null`, `undefined`, empty strings
* **Edge cases** - Zero, negative numbers, very large numbers
* **Different data types** - Strings that look like numbers, boolean values
* **Network delays** - Process parameters that might not be loaded yet

<Info>
  **Pro Tip**: Use your browser's developer console to test computed value logic before implementing it in the UI Designer. You can copy your expression and test it with sample data.
</Info>

#### Use meaningful default values

```javascript theme={"system"}
// Provide sensible defaults for fallback scenarios
if ("${application.loanType}" == "conventional") {
    return "Single-Family Home, Townhouse, Condo, Multi-Family Dwelling";
} else {
    return "Please select a loan type first"; // Clear user guidance
}
```

## Troubleshooting common issues

### Issue: Computed value not updating

**Symptoms**: UI element shows old values or doesn't change when process parameters change
**Solution**:

* Ensure every code path has a `return` statement
* Check that process parameter syntax uses `${}` correctly
* Verify the process parameter actually exists and has data

### Issue: Getting `undefined` values

**Symptoms**: UI elements appear blank or show "undefined"
**Solution**:

* Check that your JavaScript expression syntax is correct and includes `return`
* Add fallback `return` statements for all possible conditions
* Use defensive programming: `return ${application.value} || "default value"`

### Issue: Values not calculating correctly

**Symptoms**: Math operations produce unexpected results
**Solution**:

* Verify that process parameters are properly referenced with `${}` syntax
* Use `parseInt()` or `parseFloat()` for numeric operations
* Add type checking: `if (typeof ${application.value} === 'number')`

### Issue: Expression works in console but not in UI Designer

**Symptoms**: Logic works when tested separately but fails in computed values
**Solution**:

* Remember that process parameters use `${}` syntax, not regular JavaScript variables
* Ensure all code paths return values, not just the main logic
* Check for syntax errors specific to the UI Designer's JavaScript engine

## Summary

The `return` statement is not optional in computed values—it's a requirement. When testing your computed value rules:

1. **Always** include `return` statements in your JavaScript expressions
2. **Test** all possible code paths and scenarios
3. **Provide** meaningful fallback values for edge cases
4. **Verify** that your expressions work correctly across different input conditions
5. **Debug** using browser console before implementing in UI Designer

<Warning>
  **Final Reminder**: Without the `return` statement, your computed values will not function as expected, and your UI elements will not receive the calculated values they need to display correctly. This is the #1 cause of computed value failures.
</Warning>

### Quick Reference: Common Return Patterns

```javascript theme={"system"}
// Simple conditional return
return ${application.value} > 100 ? "High" : "Low";

// Multiple conditions with fallback
if (${application.status} === "active") {
    return "Status: Active";
} else if (${application.status} === "pending") {
    return "Status: Pending";
} else {
    return "Status: Unknown";
}

// Numeric calculations with validation
if (!isNaN(parseFloat(${application.amount}))) {
    return parseFloat(${application.amount}) * 1.1;
} else {
    return 0;
}

// String operations
return (${application.firstName} || "") + " " + (${application.lastName} || "");
```

***

## Hide and disable expressions

Hide and disable conditions are JavaScript expressions evaluated on the client side. They control whether a UI element is visible or interactive.

* **Hide condition**: hides the element when the expression evaluates to `true`
* **Disabled condition**: disables the element (greyed out, not interactive) when the expression evaluates to `true`

<Info>
  Hide/disable expressions use the same `${}` interpolation syntax as computed values, but they do **not** use the `return` statement. The expression is evaluated directly as a boolean.
</Info>

### Syntax reference

| Pattern                       | Expression                                                                        | Result                                     |
| ----------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------ |
| Hide if field is empty        | `${application.income} === null \|\| ${application.income} === ""`                | Hidden when income is null or empty string |
| Hide if field has a value     | `${application.income} !== null && ${application.income} !== ""`                  | Hidden when income has a value             |
| Disable based on value        | `${application.name} === 'TEST'`                                                  | Disabled when name equals "TEST"           |
| Show only for specific option | `${application.loanType} !== 'mortgage'`                                          | Hidden unless loan type is "mortgage"      |
| Hide based on boolean         | `${application.isVIP} === false`                                                  | Hidden when isVIP is false                 |
| Hide based on number          | `${application.amount} < 1000`                                                    | Hidden when amount is less than 1000       |
| Multiple conditions (AND)     | `${application.age} >= 18 && ${application.consent} === true`                     | Hidden when both are true                  |
| Multiple conditions (OR)      | `${application.status} === 'rejected' \|\| ${application.status} === 'cancelled'` | Hidden when either matches                 |

### Common pitfalls

<AccordionGroup>
  <Accordion title="Null vs empty string">
    Process data keys can be `null` (never set) or `""` (set to empty string). Always check for both:

    ```javascript theme={"system"}
    // Wrong — misses empty strings
    ${application.income} === null

    // Wrong — misses null values
    ${application.income} === ""

    // Correct — catches both
    ${application.income} === null || ${application.income} === ""
    ```
  </Accordion>

  <Accordion title="String comparison requires quotes">
    When comparing to a string value, always wrap it in quotes:

    ```javascript theme={"system"}
    // Wrong — compares to a variable named mortgage
    ${application.loanType} === mortgage

    // Correct — compares to the string "mortgage"
    ${application.loanType} === 'mortgage'
    ```
  </Accordion>

  <Accordion title="Boolean values — use strict equality">
    Boolean fields may come as `true`/`false` or as strings `"true"`/`"false"` depending on the data source:

    ```javascript theme={"system"}
    // Safe approach — handles both boolean and string
    ${application.isActive} === true || ${application.isActive} === 'true'
    ```
  </Accordion>

  <Accordion title="Nested objects — check parent exists first">
    If a parent object might be null, accessing a child property will throw an error:

    ```javascript theme={"system"}
    // Risky — fails if client is null
    ${application.client.status} === 'active'

    // Safer — check parent first
    ${application.client} !== null && ${application.client.status} === 'active'
    ```
  </Accordion>

  <Accordion title="Number comparisons — watch for string types">
    Values from form inputs may arrive as strings. Use explicit parsing if needed:

    ```javascript theme={"system"}
    // May fail if amount is a string "1000"
    ${application.amount} > 500

    // Safer for numeric comparisons
    parseInt(${application.amount}) > 500
    ```
  </Accordion>
</AccordionGroup>

### Where expressions are used

| Context                 | Syntax                  | Uses `return`?      | Evaluated             |
| ----------------------- | ----------------------- | ------------------- | --------------------- |
| **Hide condition**      | `${key} === value`      | No                  | Client-side, boolean  |
| **Disable condition**   | `${key} === value`      | No                  | Client-side, boolean  |
| **Computed values**     | `return ${key} + ...`   | Yes                 | Client-side, any type |
| **Conditional styling** | `$key.field > value`    | No                  | Client-side, boolean  |
| **Gateway conditions**  | MVEL/JS on process data | Depends on language | Server-side, boolean  |

<Tip>
  For more complex logic that depends on multiple data sources or requires server-side processing, consider using [Event Handlers](./event-handlers) (client-side JavaScript) or [business rules](../actions/business-rule-action/business-rule-action) (server-side) instead of hide/disable expressions.
</Tip>


# Event Handlers
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/event-handlers

Configure how UI components respond to user interaction and lifecycle events — run node actions, start workflows, navigate, run local scripts, and more — from a single Event Handlers panel.

## Overview

An **event handler** connects a UI component to something that happens when the user interacts with it or when a screen loads. Each handler has a **trigger** (the event, such as a click) and one or more **actions** (what runs in response, such as a node action or a workflow).

Event handlers are configured per component, in the **Event Handlers** section of the component's configuration panel. A single trigger can run an ordered chain of actions.

<CardGroup>
  <Card title="One unified panel" icon="layer-group">
    UI events, UI actions, and AI triggers are all configured as event handlers in one place
  </Card>

  <Card title="Triggers to actions" icon="bolt">
    React to On Click, On Change, On Load, and On Display with a chain of typed actions
  </Card>

  <Card title="Run local scripts" icon="code">
    Update local data on the client with a JavaScript expression — no backend roundtrip
  </Card>

  <Card title="Ordered chains" icon="list-ol">
    Sequence multiple actions per trigger, with ordering and compatibility rules enforced
  </Card>
</CardGroup>

***

## Triggers

A handler reacts to one of four trigger events. The triggers available on a component depend on the component type and the context (Process vs UI Flow).

| Trigger        | Fires when                                                                     | Typical components                                                                                                          |
| -------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **On Click**   | The user clicks the component                                                  | Button, File Upload, Bulk File Upload, Image, Text, Collection Prototype                                                    |
| **On Change**  | The component's value changes                                                  | Form fields (input, text area, select, multi-select, date picker, slider, radio, checkbox, segmented button, switch), Table |
| **On Load**    | A screen is rendered for the first time in a session                           | UI Flow: Page, Zone, Tab Bar, Modal · Process: Tab                                                                          |
| **On Display** | A screen becomes visible (initial render, navigating back, or a modal closing) | UI Flow: Page, Zone, Tab Bar · Process: Tab                                                                                 |

<Note>
  **On Load vs On Display** — On Load fires once per component per session and does not re-fire on back/forward or breadcrumb navigation. In UI Flows, an explicit **Navigate To** action resets this: the destination screen's On Load re-fires so it can re-initialize data. On Display fires every time the component becomes visible. In UI Flows, **Modal** supports On Load only.
</Note>

***

## Action types

The **Action Type** of a handler determines what runs. The available types depend on the context, the component, and the trigger.

| Action type                    | What it does                                                                                                                                             |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node Action**                | Runs a manual node action configured on the same user task node (Process context).                                                                       |
| **Start Process**              | Starts a process instance.                                                                                                                               |
| **Start Workflow**             | Triggers an integration workflow. Fire-and-forget; does not pause the current flow.                                                                      |
| **Start Project**              | Starts a new instance in another project/application.                                                                                                    |
| **Navigate To**                | Navigates to another screen within a UI Flow.                                                                                                            |
| **External**                   | Opens an external URL, optionally in a new tab. Supports `${variable}` values from data.                                                                 |
| **Upload**                     | Initiates a file upload. Available on file-upload components.                                                                                            |
| **Dismiss**                    | Dismisses a subprocess or closes a modal.                                                                                                                |
| **Run Local Script**           | Evaluates a client-side JavaScript expression and merges the result into local data — no backend roundtrip. (See [Run Local Script](#run-local-script).) |
| **Conversation Reply Trigger** | In Chat-Driven UI Flows, sends a reply trigger to the conversational agent with parameter mapping.                                                       |

**Which action types appear** depends on context, component, and trigger:

* **On Load / On Display** triggers: UI Flow → **Start Workflow** only; Process → **Node Action** only.
* **UI Flow** (other triggers): Start Process, Start Workflow, External, Navigate To, Dismiss. File-upload components add **Upload**.
* **Process** (other triggers): Node Action, Dismiss, Start Project, External. File-upload components → **Upload** only.
* **Run Local Script** is available on interactive and form-field components.
* **Conversation Reply Trigger** is available in UI Flow context when a chat surface is in scope.

***

## Configuring an event handler

Event handlers are configured in the **Event Handlers** section of the selected component's configuration panel.

<Steps>
  <Step title="Select the component">
    In the UI Designer, select the component (button, form field, page, modal, and so on) that should respond to an event.
  </Step>

  <Step title="Add a handler for a trigger">
    In the **Event Handlers** section, click **+** and choose the trigger event (On Click, On Change, On Load, or On Display). Handlers are grouped under their trigger.
  </Step>

  <Step title="Choose the action type and configure it">
    Pick an **Action Type** and fill in its fields (see [Action types](#action-types)). For example, a **Node Action** needs a **Node Action Name**; **External** needs a **URL**; **Start Workflow** needs a **Workflow**.
  </Step>

  <Step title="Order the chain (optional)">
    When a trigger has more than one action, drag handlers to set their execution order. The editor flags ordering or compatibility violations.
  </Step>

  <Step title="Save">
    Save the handler. Each handler is stored as an ordered action on the component's template configuration.
  </Step>
</Steps>

### Common handler options

Depending on the action type, a handler can include:

* **Show loader** — display a loader until a server-side event updates the data or screen.
* **Open in new tab** — for External actions, open the URL in a new tab.
* **Dismiss on completion** — dismiss the modal as part of a user-triggered action.
* **Hide Subprocess Navigation** — disable navigation to subprocesses (requires Open in new tab).
* **Add form to submit** — link the action to forms whose fields are validated before it runs (see [Form validation](#form-validation)).
* **Add custom keys / Exclude keys / Add custom body** — shape the data sent with the action.

***

## Action chains

A single trigger can run several actions in sequence. The Designer enforces three kinds of rules:

* **Per-type limits** — one action of each type per trigger, except **Run Local Script**, which allows up to **five**.
* **Compatibility** — some action types cannot coexist on the same trigger. For example, in a UI Flow, **Start Process** cannot be combined with Navigate To, Dismiss, External, or Conversation Reply Trigger. The rules differ between UI Flow and Process contexts; custom components are exempt.
* **Ordering** — handlers run as a sequential chain in the order shown. Some types cannot follow others; the editor blocks invalid orderings. If an action in the chain fails, the local data-store changes made earlier in the chain are **rolled back**.

***

## Run Local Script

The **Run Local Script** action evaluates a JavaScript expression on the client and merges the returned object into the local data store. There is no backend roundtrip, so the UI updates instantly. This is the same client-side mechanism that was previously called a "UI event."

<Warning>
  **Data availability** — a Run Local Script expression can only access data already sent from the backend to the frontend for display on the current screen. Referencing a property that isn't on the page will cause the expression to fail.
</Warning>

### Writing the expression

Use the same `${}` syntax as [computed values](./dynamic-and-computed-values#computed-values). Instead of returning a single value, return an object that updates the local data store:

```javascript theme={"system"}
// Access data using ${} syntax
const calculatedValue = ${client.debt} / ${client.income};

// Return an object to update local data
return {
  "client": {
    "debtPercentage": calculatedValue
  }
}
```

| Aspect             | Business Rule            | Run Local Script  |
| ------------------ | ------------------------ | ----------------- |
| **Logic language** | Python, JavaScript, MVEL | JavaScript only   |
| **Output syntax**  | `output.put(key, value)` | `return { }`      |
| **Execution**      | Server-side              | Client-side (SDK) |
| **Latency**        | Network roundtrip        | Instant           |

Values updated by Run Local Script remain **local to the UI** until a submit action sends them to the process engine. On an On Click handler, the script evaluates before any other action on the same trigger — useful for setting a selected item's ID right before an action fires.

<Tabs>
  <Tab title="Calculate percentage">
    ```javascript theme={"system"}
    const prc = ${client.debt} / ${client.income};
    return { "client": { "debtPrc": prc } }
    ```
  </Tab>

  <Tab title="Conditional value">
    ```javascript theme={"system"}
    const amount = ${app.loanAmount};
    const status = amount > 100000 ? "high" : "standard";
    return { "app": { "riskCategory": status } }
    ```
  </Tab>

  <Tab title="Array totals">
    ```javascript theme={"system"}
    const items = ${order.items} || [];
    const total = items.reduce((sum, item) => sum + item.price, 0);
    return { "order": { "totalAmount": total, "itemCount": items.length } }
    ```
  </Tab>
</Tabs>

<Tip>
  Keep Run Local Script expressions lightweight — they run synchronously on the UI thread. For heavy logic, use a server-side business rule. In Reusable UI Templates, any keys referenced in the expression must be mapped through the template's input parameters.
</Tip>

***

## Form validation

When a handler has one or more forms linked via **Add form to submit**, the platform validates all visible, enabled fields in those forms before the action runs. If any field fails, the action is blocked and errors are shown.

<Warning>
  **Hidden and disabled fields skip validation.** When a field is hidden by a hide condition, its validators are removed and any errors are cleared (they re-apply when it becomes visible). Disabled fields are also treated as valid. This prevents invisible fields from blocking progress — if you rely on validation for data integrity, give hidden fields valid defaults or validate them on the backend.
</Warning>

<Tip>
  If no forms are selected in **Add form to submit**, no client-side validation runs and the action executes immediately. Use this for "Save as Draft"-style actions that should allow incomplete data.
</Tip>

***

## Action specifics

### External

External actions open a URL, optionally in a new tab. URLs support `${variableName}` placeholders resolved from process data at runtime (a missing variable resolves to `null`):

* `https://example.com/users/${userId}`
* `${externalSystemUrl}/api/resource`

### Start Workflow

Select the **Workflow** to trigger and provide **Start params**. When triggered from a button inside a modal, **Dismiss modal** dismisses the modal as part of the action.

<Warning>
  Start Workflow is fire-and-forget — it does not pause the current process or wait for the workflow to finish.
</Warning>

### Dismiss

Dismiss calls the backend to dismiss the current process instance and sets the process and its active subprocesses to the terminal **DISMISSED** state. It requires only a name and optional analytics parameters — no form submission or custom keys.

<Note>
  A modal's own **Dismissible** property (close-on-backdrop-click and optional confirmation alert) is separate from the Dismiss action. For modal lifecycle guidance, see [Process design principles](../process/design-principles#modals-are-dismissed-only-by-user-interaction).
</Note>

***

## Migrating from UI events and UI actions

In 5.1.x, three separate surfaces existed: **UI events** (client-side expressions), **UI actions** (backend interactions), and **AI triggers** (conversation replies). In 5.9.0 they are unified into Event Handlers:

| 5.1.x                                                                     | 5.9.0                                               |
| ------------------------------------------------------------------------- | --------------------------------------------------- |
| UI event expression (`onChange` / `onClick` / `onLoad` / `onDisplay`)     | **Run Local Script** action on the matching trigger |
| UI action (Node Action, Start Process, External, Navigate To, Dismiss, …) | The corresponding **action type** on a handler      |
| AI trigger (conversation reply)                                           | **Conversation Reply Trigger** action               |

The trigger names map one-to-one (`onClick` → On Click, `onChange` → On Change, `onLoad` → On Load, `onDisplay` → On Display). Behavior is unchanged — Run Local Script still evaluates a client-side expression and merges the result into local data. The storage model changed: handlers are now backend-persisted, ordered action objects on the component's template configuration rather than inline `flowxProps.events` entries.

***

## Related resources

<CardGroup>
  <Card title="Dynamic & computed values" icon="wand-magic-sparkles" href="./dynamic-and-computed-values">
    Expressions for hide conditions and computed values
  </Card>

  <Card title="Validators" icon="check" href="./validators">
    Configure validation rules for form fields
  </Card>

  <Card title="Buttons" icon="square" href="./ui-component-types/buttons">
    Configure button components that trigger event handlers
  </Card>

  <Card title="Adding an action to a node" icon="plus" href="../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node">
    Configure the node actions that Node Action handlers call
  </Card>
</CardGroup>


# Layout configuration
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/layout-configuration

Layout settings are available for all components that can group other types of elements (for example, Containers or Cards).

The layout configuration settings enable users to customize key properties, including layout direction, alignment, gap, sizing, and spacing, to create visually appealing and functional designs.

<Frame>
  <video />
</Frame>

These settings can be applied practically in various ways, depending on the context and purpose of the design:

* **Layout Direction and Alignment**: Use these settings to control how content is displayed, ensuring a logical and visually appealing arrangement. For example, a left-to-right layout direction suits languages that read from left to right, while center alignment is ideal for headings or titles.
* **Gap, Sizing, and Spacing**: Manage the distance between elements to create a sense of hierarchy and balance. Adjusting spacing between paragraphs or sections can improve readability, while resizing elements can prioritize certain components within the design.
* **Accessibility Considerations**: Customizing layout direction, alignment, spacing, and sizing can enhance the accessibility and inclusivity of your design. For example, adjusting these settings can make content more readable for users with disabilities or those using assistive technologies. For more information, see the [Accessibility guide](../../platform-deep-dive/accessibility).

## Linear layout

The Linear layout arranges child elements in a single line, either horizontally or vertically.

<Frame>
  <video />
</Frame>

### Linear layout configuration properties

<Steps>
  <Step title="Display Mode">
    **Linear**: Selected by default for arranging child elements in a linear fashion.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/set_linear.png)
    </Frame>
  </Step>

  <Step title="Direction">
    * **Horizontal**: Aligns child elements horizontally in a row.
    * **Vertical**: Aligns child elements vertically in a column.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_direction.gif)
    </Frame>
  </Step>

  <Step title="Justify">
    Controls the alignment of child elements along the main axis (the direction set by Horizontal or Vertical).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_justify.gif)
    </Frame>

    Options include:

    * **Start**: Aligns elements at the start of the container.
    * **Center**: Centers elements along the main axis.
    * **End**: Aligns elements at the end of the container.
    * **Space Between**: Distributes elements evenly with space between them.
    * **Space Around**: Distributes elements with space around them.
    * **Space Evenly**: Distributes elements with equal space around them.
  </Step>

  <Step title="Align">
    Controls the alignment of child elements along the cross axis (perpendicular to the main axis).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_align.gif)
    </Frame>

    Options include:

    * **Start**: Aligns elements at the start of the cross axis.
    * **Center**: Centers elements along the cross axis.
    * **End**: Aligns elements at the end of the cross axis.
    * **Stretch**: Stretches elements to fill the container along the cross axis.
  </Step>

  <Step title="Wrap">
    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_wrap.gif)
    </Frame>

    * **Enabled** (Yes): This option allows elements to wrap onto multiple lines when they exceed the container's width along the main axis, ensuring a flexible and responsive layout.
    * **Disabled** (No): This option forces all elements to remain on a single line, even if they overflow beyond the container's width, potentially causing elements to be clipped or hidden.
  </Step>

  <Step title="Gap">
    Sets the spacing between child elements, measured in pixels.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_gap.gif)
    </Frame>
  </Step>
</Steps>

To better understand how these layout configurations work and see real-time feedback on different combinations, please refer to the following link:

<Card title="Layout configuration" icon="link" href="https://tburleson-layouts-demos.firebaseapp.com/#/docs" />

## Grid layout

In addition to linear (flex-based) layouts, you can configure components using a grid layout. This option is particularly useful for designs requiring a more structured and multi-dimensional arrangement of elements.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout.png)
</Frame>

### Switching layout types

For components that contain child elements (such as Containers, Cards, and Forms), you can switch between a linear layout and a Grid layout using a layout picker. The default layout is linear, but you can select Grid to arrange your content in a more structured way.

<Frame>
  <video />
</Frame>

### Platform-specific layouts

You can configure different layout settings for different platforms. For example, you can opt for a grid layout on the web but switch to a linear layout on mobile for a more simplified user experience. This flexibility ensures that the design is responsive and optimized for each platform, improving usability across different devices.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/layout_platform_specific.gif)
</Frame>

#### Configuring the grid

Once the Grid layout is selected, you can define the number of columns. Initially, the columns will be distributed equally, meaning all columns will have the same width. Additional customization options include:

* **Number of Columns**: Set the number of columns for the grid. By default, grid will use two columns.
* **Alignment**: Control how child elements are aligned within the grid. Alignment can be adjusted both horizontally and vertically, ensuring that content is positioned exactly where needed.
* **Gap Configuration**: Customize the gap between columns and rows. The default gap is inherited from the parent component's theme settings, ensuring consistency across your design.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_specs.png)
</Frame>

#### Grid child settings

When configuring a grid, individual child components can be further customized:

* **Column Span**: Set how many columns a child component should span across.

<Warning>
  Col Span should not exceed the number of parent grid columns.
</Warning>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout_child_settings.gif)
</Frame>

* **Row Span (Web Only)**: Set how many rows a child component should span.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout_child_settings1.gif)
</Frame>

#### Order property

The Order property controls the arrangement of elements within grid layouts. By default, elements follow the order in which they appear in the parent component's array. However, this order can be customized using the following options:

* **Auto**: The default setting that retains the order of elements as defined in the array (default value is `0`).
* **First**: Moves the element to the first position by setting its order to `-999`.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/order_first.gif)
</Frame>

* **Last**: Moves the element to the last position by setting its order to `999`.
* **Manual**: Allows for custom ordering by setting a specific numerical value.

<Tip>
  Example: In a Grid with 10 elements, setting one element's order to `5` while the others are set to `auto` (which equals `0`) will place that element last, because `5` is greater than `0`.
</Tip>

#### Alignment in grid layouts

Proper alignment within grid layouts is essential, particularly when working with fixed-width columns or rows. By default, child elements will inherit alignment settings from their parent component, ensuring a consistent look and feel.

However, you have the flexibility to override these default settings for individual child elements, allowing precise control over horizontal and vertical alignment. This customization is key to achieving the desired visual structure, especially when certain elements need specific positioning within the grid.

### Component details

* **Components with gridLayout Property**: The following components support the `gridLayout` property:
  * [**CONTAINER**](./ui-component-types/root-components/container)
  * [**CARD**](./ui-component-types/root-components/card)
  * **FORM**
  * [**COLLECTION**](./ui-component-types/collection)
  * [**COLLECTION PROTOTYPE**](./ui-component-types/collection/collection-prototype)
* **Components with gridChild Property**: All components can have the `gridChild` property, depending on their parent component's layout.
* **Collection gridLayout**: Within collections, the `gridLayout` property specifies only the number of columns, rowGap, and columnGap.
* **Collection Prototype**: The collection prototype does not include the `gridChild` property.
* **Grid and Flex Layout Application**: The grid and flex layouts apply exclusively to the layout of child components. Elements such as Card titles, subtitles, and Form titles are excluded from these layout types.

### Default style properties

* **Grid Layout Defaults**:
  * **Columns**: 2
  * **ColumnGap**: Inherited from component theming gap
  * **RowGap**: Inherited from component theming gap
  * **Position**: Start Start (aligning items to the start both horizontally and vertically)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout_defaults.png)
</Frame>

* **Grid Child Defaults**:
  * **Position**: Start Start (aligned to the start of both axes)
  * **ColumnSpan:** 1 (spans a single column)
  * **RowSpan (Web)**: 1 (spans a single row)
  * **Order**: 0 (Auto, maintaining the default order of elements)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_child_defaults.png)
</Frame>

***

### Example using grid layout

**Use case**: **Customer Information Form**

This scenario involves a banking application that requires detailed input from a company representative, either during onboarding or for a loan application. Given the need to gather extensive information, a form with a 2-column grid layout is used to ensure clean and consistent alignment of fields.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/example_gridd.png)
</Frame>

<Tip>
  For forms requiring additional inputs, consider adjusting the **Columns** property to match the number of fields needed. Expanding the form layout will help organize the inputs efficiently and improve user experience.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/more_columns.gif)
</Tip>

<AccordionGroup>
  <Accordion title="Role and Name">
    * Collect the company representative’s role and name.
    * A 2-column grid layout can display the *Role* in one column and *Name* in the other, ensuring fields are aligned and easy to access.
  </Accordion>

  <Accordion title="Shareholder Status">
    * A toggle or checkbox asks if the representative is the main shareholder and/or the ultimate beneficial owner.
    * A 2-column grid places these toggles side by side for a cleaner interface.
  </Accordion>

  <Accordion title="Personal Details">
    * Fields like *First Name*, *Personal Identification Number*, *Date of Birth*, and *Country of Residence* are collected.
    * The 2-column grid aligns these fields horizontally, with appropriate spacing for readability.
  </Accordion>

  <Accordion title="Contact Details">
    * Collects *Phone Number*, *Email*, and *Preferred Method of Contact*.
    * The grid places *Phone Number* and *Email* side by side, while the *Preferred Method of Contact* dropdown spans the row.
  </Accordion>

  <Accordion title="Residence Address">
    * Collect *State*, *Country*, and *City*.
    * A 3-column grid displays these fields in a single row, simplifying navigation for the user.
  </Accordion>

  <Accordion title="Employment Seniority">
    * Capture employment history such as *Total Service Duration* and *Verified By*.
    * A 2-column grid aligns these fields for easy comparison, avoiding misalignment or unnecessary gaps.
  </Accordion>

  <Accordion title="Union Membership">
    * A simple yes/no radio button for union membership.
    * A grid layout ensures the options are neatly aligned for a clean, straightforward selection.
  </Accordion>
</AccordionGroup>

***

### Best Practices

To ensure an optimal user experience and consistent visual design, consider these best practices when using grid layouts:

* **Minimize Fixed Widths**: Avoid using fixed widths for child components in a grid. Relying on flexible sizing allows the grid to adapt smoothly across different screen sizes and devices. Only use fixed widths when absolutely necessary (e.g., for icons or buttons with defined sizes).

* **Consider Total Width**: If you know the width of the screen is `X`, ensure that the total width of your fixed-width elements doesn't exceed `X`. This prevents layout issues like content overflow or misalignment across different devices.

* **Use Column Span Thoughtfully**: When setting the `columnSpan` for a grid child, ensure that the total spans across all elements do not exceed the number of columns. This ensures a consistent and predictable layout.

* **Avoid Overcrowding**: When adding numerous child components to a grid, be mindful of spacing (gaps) between elements. Proper use of `rowGap` and `columnGap` helps maintain clarity and reduces visual clutter.

* **Use Default Inheritance**: Utilize the default alignment inheritance from the parent grid to ensure consistency. Only override alignment on child components when specific visual differences are needed.

* **Use `Auto` Order When Possible**: Stick with the `auto` order setting for most child components, unless a specific element needs to appear first or last. This will help maintain logical reading and visual flow without complex manual ordering.

* **Always Be Mindful of Mobile Screen Width**: When designing for mobile, always consider the narrower screen width. Ensure that grid layouts adapt gracefully, perhaps switching from a grid to a linear layout, or adjusting spacing and sizing to fit within the mobile screen's constraints without causing overflow or misalignment.

* **Test Across Platforms**: Given potential differences in behavior between web, iOS, and Android platforms, test your grid layout across these platforms to ensure consistent performance and avoid unexpected behavior like overflow or misalignment.

* **Avoid Fixed Widths on Columns**: Instead of setting fixed widths on the entire column, apply fixed widths to the individual elements inside the grid cells. This ensures more flexible layouts that adapt to different screen sizes, especially on mobile devices, without causing issues like overflow or misalignment.

### FAQs

<AccordionGroup>
  <Accordion
    title="I have a Grid with 10 elements, and I set one element's order to `5`. Why is it not displayed as the fifth element?
"
  >
    **A:** The order property works relative to other elements. If other elements are set to `auto` (which equals `0`), then the element with order `5` will be placed after all the `0` elements, making it appear last.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/FAQ1.gif)
    </Frame>
  </Accordion>

  <Accordion title="What should I be cautious about when working with a Grid layout?">
    **A:** Be careful with using fixed widths in Grid layouts. Fixed widths can lead to unexpected behavior, especially on different devices. It's better to use flexible sizing options whenever possible to maintain a responsive and predictable design.
  </Accordion>
</AccordionGroup>


# Localization and internationalization
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/localization-and-i18n

FlowX.AI localization and internationalization adapt applications to different languages, regions, and formats, enhancing the user experience with dynamic date, number and currency formatting.

<video />

## Internationalization

Internationalization (i18n) in FlowX.AI enables apps to be adapted for multiple languages and regions without altering the core code. It sets the foundation for localization by handling language structure, layout adjustments, and supporting various formats.

<Tip>
  To set the default language at the application level, navigate to **Projects -> Application -> Settings**.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application_language.png)
</Tip>

## Localization

Locale settings impact all date, number, and currency formats based on the combination of region and language. The language dictates translations, while the region specifies formatting order and conventions.

### Locale sources

Locale settings are derived from two main sources:

* **Container Application**: Provides global locale settings across the application.

<Info>
  If not specified during deployment, the default locale will be set to `en-US`.
</Info>

<Tip>
  When you pass `language` and `locale` as URL query parameters (e.g., `?language=ro&locale=ro-RO`), the SDK automatically preserves them across navigation and page refreshes. You don't need to store them in session storage.
</Tip>

* **Application Level**: Enables context-specific overrides within the application for formatting Numbers, Dates, and Currencies.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/app_lvl_format.png)
</Frame>

## Core i18n & l10n features

### Date formats

The default date format in FlowX.AI is automatically determined by the default locale set at the application or system level. Each locale follows its region-specific date convention.

For example:

* en-US locale (United States): `MM/DD/YYYY` → 09/28/2024

<Tip>
  You can set date formats at the application level (as you can see in the example above), choosing from five predefined options: short, medium, long, full, or custom (e.g., dd/mm/yy).

  Additionally, date formats can be overridden at the UI Designer level for specific UI elements that support date customization.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/override_custom.png)
  </Frame>
</Tip>

UI Elements supporting date formats:

* Text
* Link
* Message
* Datepicker

FlowX.AI will apply the following formatting options, adapting to the region's standard conventions:

| Format Type | Format Pattern        | Example                        | Description                                |
| ----------- | --------------------- | ------------------------------ | ------------------------------------------ |
| **Short**   | `MM/dd/yy`            | `08/28/24`                     | Month before day, two-digit year.          |
| **Medium**  | `MMM dd, yyyy`        | `Sep 28, 2024`                 | Abbreviated month, day, four-digit year.   |
| **Long**    | `MMMM dd, yyyy`       | `September 28, 2024`           | Full month name, day, and four-digit year. |
| **Full**    | `EEEE, MMMM dd, yyyy` | `Thursday, September 28, 2024` | Full day of the week, month, day, year.    |
| **Custom**  | `dd/MM/yyyy`          | `28/08/2024`                   | User-defined format; day before month.     |

<Info>
  The date formats shown in the example are based on the **en-US (United States English) locale**, which typically uses the month-day-year order.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/date_formats.png)
</Frame>

<Tip>
  If the predefined date formats do not met your needs you can declare and use a custom date format (both at application level or override in UI Designer).
</Tip>

The following example will demonstrate how to set and display various date formats using text UI elements. We will override the default format (originating from the application level) directly in the UI Designer to showcase all available formats:

<video />

<Info>
  FlowX.AI formats dates using [**ISO 8601**](https://www.iso.org/iso-8601-date-and-time-format.html) for consistent and clear international representation.
</Info>

### Number formatting

FlowX.AI adjusts number formats to align with regional standards, including the use of appropriate decimal separators and digit grouping symbols. This ensures that numbers are displayed in a familiar format for users based on their locale.

#### Locale-specific formatting

Formatting the numbers to adapt decimal separators (`comma` vs. `dot`) and digit grouping (`1,000` vs. `1.000`) to match regional conventions.

<Tip>
  The correct formatting for a number depends on the locale. Here's a quick look at how the same number might be formatted differently in various regions:

  * **en-US (United States)**: 1,234.56 (comma for digit grouping, dot for decimals)
  * **de-DE (Germany)**: 1.234,56 (dot for digit grouping, comma for decimals)
  * **fr-FR (France)**: 1 234,56 (space for digit grouping, comma for decimals)
  * **es-ES (Spain)**: 1.234,56 (dot for digit grouping, comma for decimals)
</Tip>

#### Decimal precision

You can set minimum and maximum decimal places for numbers in application settings to store data and display it with the required precision in the data store.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/app_number_formatting.png)
</Frame>

<Info>
  Formatting settings defined in the FlowX.AI props in the UI Designer take precedence over the application-level formatting settings.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/min_max_decimals.png)
  </Frame>
</Info>

<Tip>
  For UI elements that support `number` or `currency` types, FlowX.AI checks the data model for precision settings and applies them during data storage, ensuring consistency to configured precision levels.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/darta_model_precision.png)

  This means that when using a `float` data model attribute, the precision settings directly control how the number is saved in the data store, specifying the maximum number of decimal places that can be stored.

  <Info>
    Additionally, an for input UI elements a mask is applied to prevent users from entering more decimal places than the precision set, ensuring data integrity and compliance with defined formatting rules.
  </Info>

  For more details, refer to [Data model integration](#data-model-integration).
</Tip>

* **Minimum Decimals**: Sets the least number of decimal places that a number will display. If a number has fewer than the specified decimals, trailing zeros will be added to meet the requirement.
* **Maximum Decimals**: Limits the number of decimal places a number can have. If the number exceeds this limit, it will be rounded to the specified number of decimals.

**Example**:

If you set both Minimum and Maximum Decimals to 3, a number like 2 would display as 2.000, and 3.14159 would be 3.141.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/min_max_decimals_ex.gif)
</Frame>

<Info>
  At runtime, the system applies number formatting rules based on the locale and the settings defined in the application's configuration or UI Designer overrides.

  If the number is linked to a data model key the formatting adheres to the metadata defined there, ensuring consistent rendering of numerical data.
</Info>

### Currency formatting

FlowX.AI provides currency formatting features that dynamically adapt to regional settings, ensuring accurate representation of financial data.

#### Currency object structure

Currencies are managed as a system object with `amount` and `code` keys, creating a wrapper that facilitates consistent handling. This design ensures that every currency display corresponds accurately to the regional and formatting standards defined by the locale. If the `code` is not provided, the system uses the locale to determine the appropriate currency symbol or code.

#### Display behavior

When displaying currency values, the system expects keys like `loanAmount` to have both `amount` and `code` properties. For example, with the locale set to `en-US`, the output will automatically follow the US formatting conventions, displaying amounts like "\$12,000.78" when the currency is USD.

* If the value found at the key path is not an object containing `amount` or `code`, the system will display the value as-is if it is primitive. If it's an object, it will show an empty string.
* If the key path is not defined, similar behavior applies: primitive values are displayed as-is, and objects result in an empty string.

#### Locale-sensitive formatting

Currency formatting depends primarily on the region defined by the locale, not the language.

<Info>
  When the currency `code` is `null`, the system defaults to the currency settings embedded within the locale, ensuring region-specific accuracy.
</Info>

#### Dynamic formatting in UI

FlowX dynamically applies number formatting within UI components, such as inputs and sliders. These components adjust in real-time based on the current locale, ensuring that users always see numbers in their preferred format. UI components that support currency values dynamically format them in real time. For example:

* Input fields with `CURRENCY` types save values in `{key path}.amount` and will delete the entry from the data store if the input is empty.
* Sliders will save integer values (with no decimals) to `{key path}.amount` and format the displayed values, including min/max labels, according to the locale and currency.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/slider_min_max.gif)
</Frame>

**Formatting Text with locale and data from UI elements**

This example demonstrates how to format a dynamic text by substituting placeholders with values from a data store, taking into account locale-specific formatting. In this case, the goal is to insert the value  coming from a key called loanAmount (added on an Input UI element) into a text and format it according to the en-US locale.

**Data store**:

A JSON object containing key-value pairs. The `loanAmount` key holds a currency object with two properties:

* amount: The actual loan value (a float or number).
* code: The currency code in ISO format (e.g., "USD" for US Dollars).

```json{ theme={"system"}
  "loanAmount": {
    "amount": 12000.78,
    "code": "USD"
  }
}
```

**Locale**

The locale determines the number and currency formatting rules, such as the use of commas, periods, and currency symbols.

Locale: en-US (English - United States)

**Processing**

* Step 1: The platform extracts the loanAmount.amount value (12000.78) and the loanAmount.code from the data store.
* Step 2: Format the amount according to the specified locale (en-US). In this locale:
  * Use a comma , to separate thousands.
  * Use a period . to denote decimal places.
* Step 3: Replace the `${loanAmount}` placeholder in the text with the formatted value \$12,000.78.

**Output**

The resulting text with the formatted loan amount and the appropriate currency symbol for the en-US locale.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/loanAmount.gif)
</Frame>

Here is the data extracted from the data store (it is available on the process instance)

<Tip>
  For instance, with a Romanian locale (`ro-RO`), currency is displayed like "12.000,78 RON" when the `code` is null or unavailable.
</Tip>

## Data model integration

FlowX.AI integrates number formatting directly with the data model. When keys are set to number or currency types, the system automatically checks and applies precision settings during data storage. This approach ensures consistency across different data sources and UI components.

Integration Details:

* Numbers are broken down into integer and decimal parts, stored according to specified precision.
* Currency keys are managed as wrapper objects containing amount and code, formatted according to the locale settings.

## UI Designer integration

Formatting is dependent on the locale, which includes both language and region settings. The application container provides the locale for display formatting.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/locale_language_ui_designer.png)
</Frame>

Formatting settings (which is by default `auto`) can be switched to `manual` and overridden for text, message, and link components within the UI Designer's properties tab.

<video />

The UI Designer enables application-level formatting settings for localized display of dynamic values.

## Supported components

* **Text/Message/Link**: Override general localization settings to match localized content presentation.
* **Input Fields**: Inputs correctly format currency and number types based on regional settings.
* **Sliders**: Currency formatting for sliders, with suffixes disabled when currency types are detected.
* **Datepickers**: Date formatting


# Buttons
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/buttons

Interactive button components for triggering actions and file uploads with comprehensive styling and configuration options.

Buttons are essential interactive elements that enable users to trigger actions, navigate between sections, and upload files. FlowX.AI provides two specialized button types, each optimized for specific use cases with extensive customization options.

<Frame>
  ![Button types overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/basic_buttons.png#center)
</Frame>

## Button types overview

Choose the right button type for your specific use case:

<CardGroup>
  <Card title="Basic Button" icon="hand-pointer" href="#basic-button">
    Trigger actions like process advancement, sending notifications, or opening new content
  </Card>

  <Card title="File Upload Button" icon="file-arrow-up" href="#file-upload-button">
    Enable file selection with built-in validation for file types and sizes
  </Card>
</CardGroup>

## Basic button

Basic buttons serve as the primary interaction mechanism for users to perform actions within your application. They can trigger process flows, send notifications, navigate to different sections, or execute business logic.

### Configuration overview

<CardGroup>
  <Card title="Properties" icon="gear">
    Labels and basic settings
  </Card>

  <Card title="Event Handlers" icon="bolt">
    Event handling and action types
  </Card>

  <Card title="Styling" icon="palette">
    Visual appearance and icons
  </Card>
</CardGroup>

### Basic button properties

<AccordionGroup>
  <Accordion title="Label Configuration" icon="tag">
    **Purpose**: Define the text displayed on the button

    **Features**:

    * Supports Markdown syntax for rich formatting
    * Dynamic text from process data
    * Localization support for multi-language applications
    * Responsive text scaling

    **Best Practices**:

    * Use action-oriented language ("Submit", "Continue", "Send")
    * Keep labels concise but descriptive
    * Consider button context and user expectations
    * Use consistent terminology across the application

    <Tip>
      Action buttons should clearly indicate what will happen when clicked. Use verbs like "Save Changes" instead of generic terms like "OK".
    </Tip>
  </Accordion>
</AccordionGroup>

### Event handlers configuration

Define the behavior when users interact with your button:

<Tabs>
  <Tab title="Event Types">
    | Event     | Description                             | Use Cases               |
    | --------- | --------------------------------------- | ----------------------- |
    | **CLICK** | Triggered when button is clicked/tapped | All button interactions |

    <Info>
      While CLICK is the primary event, the action type determines what happens when the event occurs.
    </Info>
  </Tab>

  <Tab title="Action Types">
    **Available Actions**:

    * **Process Actions**: Advance workflow, complete tasks
    * **Navigation**: Move between pages or sections
    * **Data Operations**: Save, submit, or validate data
    * **External Integrations**: Call APIs, send notifications
    * **UI Updates**: Show/hide elements, update content

    <Frame>
      ![Event handler configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/button1.png)
    </Frame>
  </Tab>

  <Tab title="Advanced Configuration">
    **Conditional Actions**: Execute different actions based on conditions

    * User roles and permissions
    * Form validation states
    * Process instance data
    * External system responses

    **Error Handling**: Define fallback behaviors

    * Network connectivity issues
    * Permission errors
    * Validation failures
    * System unavailability

    <Tip>
      For detailed event handler configuration, see the [Event Handlers guide](../event-handlers).
    </Tip>
  </Tab>
</Tabs>

### Button styling & visual design

#### Button types

Choose from four distinct visual styles to match your design system:

<Tabs>
  <Tab title="Primary">
    **Purpose**: Main call-to-action buttons

    **Characteristics**:

    * High contrast, prominent appearance
    * Usually one per screen/section
    * Draws immediate attention

    **Use Cases**: Submit forms, confirm actions, proceed to next step
  </Tab>

  <Tab title="Secondary">
    **Purpose**: Supporting actions of moderate importance

    **Characteristics**:

    * Less prominent than primary
    * Complementary to primary actions
    * Clear but not dominant

    **Use Cases**: Cancel operations, alternative paths, secondary features
  </Tab>

  <Tab title="Ghost">
    **Purpose**: Subtle actions that don't compete with primary content

    **Characteristics**:

    * Transparent background with border
    * Minimal visual weight
    * Integrates with content

    **Use Cases**: Optional actions, toggles, less critical functions
  </Tab>

  <Tab title="Text">
    **Purpose**: Minimal visual impact for tertiary actions

    **Characteristics**:

    * No background or border
    * Looks like clickable text
    * Lowest visual hierarchy

    **Use Cases**: Links, minor actions, text-based navigation
  </Tab>
</Tabs>

<Frame>
  ![Button type demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/button_type.gif)
</Frame>

<Tip>
  For comprehensive CSS styling options, check our [Styling Guide](../ui-designer#styling).
</Tip>

#### Icon integration

Enhance your buttons with meaningful icons:

<AccordionGroup>
  <Accordion title="Icon Configuration" icon="image">
    **Icon Key**: Select from the Media Library

    * Consistent icon set across the application
    * SVG format for scalability
    * Optimized for different screen sizes

    **Icon Color**: Customize appearance

    * Use color picker for precise control
    * Maintain accessibility contrast ratios
    * Consider colorblind accessibility

    <Check>
      When setting colors, the entire icon fill changes. Avoid color modifications on multicolor icons to prevent visual distortion.
    </Check>
  </Accordion>

  <Accordion title="Icon Positioning" icon="image">
    **Available Positions**:

    | Position   | Description      | Visual Result | Best For            |
    | ---------- | ---------------- | ------------- | ------------------- |
    | **Left**   | Icon before text | 🔍 Search     | Most common layout  |
    | **Right**  | Icon after text  | Submit ➤      | Directional actions |
    | **Center** | Icon only        | 🔍            | Icon-only buttons   |

    <Tip>
      When using center position, the button displays only the icon. Ensure the icon clearly communicates the action to maintain usability.
    </Tip>

    <Frame>
      ![Icon-only button example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/button_icon.png)
    </Frame>
  </Accordion>
</AccordionGroup>

## File upload button

File upload buttons provide a specialized interface for file selection with built-in validation and user feedback. They're essential for document submission, image uploads, and data import workflows.

### Configuration overview

File upload buttons share many properties with basic buttons but include specialized file handling features:

<CardGroup>
  <Card title="File Properties" icon="file">
    File type restrictions and validation
  </Card>

  <Card title="Validation" icon="shield-check">
    Size limits and error handling
  </Card>

  <Card title="User Experience" icon="user">
    Feedback and progress indication
  </Card>
</CardGroup>

### File upload properties

<AccordionGroup>
  <Accordion title="Label Configuration" icon="tag">
    **Purpose**: Clearly indicate the upload purpose

    **Examples**:

    * "Upload Document"
    * "Select Profile Picture"
    * "Import Data File"
    * "Attach Receipt"

    **Best Practices**:

    * Specify what type of file is expected
    * Include file requirements in the label if space allows
    * Use progressive disclosure for complex requirements
  </Accordion>

  <Accordion title="File Type Restrictions" icon="filter">
    **Purpose**: Control which file types users can select

    **Configuration Options**:

    | Specification           | Example                         | Purpose                    |
    | ----------------------- | ------------------------------- | -------------------------- |
    | **MIME Categories**     | `audio/*`, `image/*`, `video/*` | Broad category filtering   |
    | **Specific MIME Types** | `application/pdf`, `text/csv`   | Exact format control       |
    | **File Extensions**     | `.doc`, `.docx`, `.jpg`, `.png` | User-friendly restrictions |

    **Common Combinations**:

    ```
    Images: image/*, .jpg, .jpeg, .png, .gif, .webp
    Documents: .pdf, .doc, .docx, .txt, .rtf
    Spreadsheets: .xls, .xlsx, .csv
    Archives: .zip, .rar, .7z
    ```

    <Warning>
      Be specific about accepted file types to prevent user confusion and reduce invalid uploads.
    </Warning>
  </Accordion>

  <Accordion title="File Size Management" icon="maximize">
    **Max File Size**: Set appropriate limits based on:

    * Server capacity and processing power
    * Network bandwidth considerations
    * Storage limitations
    * User experience expectations

    **Size Guidelines**:

    * **Images**: 5-10 MB for high quality
    * **Documents**: 25-50 MB for complex files
    * **Data Files**: Based on processing requirements
    * **Media Files**: 100+ MB for videos

    **Error Messages**: Provide clear feedback

    * "File size must be under 10 MB"
    * "Please compress your image and try again"
    * "Large files may take longer to process"
  </Accordion>

  <Accordion title="Validation & Error Handling" icon="triangle">
    **Invalid File Type Error**: Custom messages for unsupported formats

    * Explain what formats are accepted
    * Provide guidance on file conversion
    * Link to help resources if needed

    **Max File Size Error**: Clear size limit communication

    * Display the exact limit
    * Suggest file compression tools
    * Offer alternative upload methods for large files

    **Example Configuration**:

    ```
    Invalid Type: "Please upload PDF, DOC, or DOCX files only"
    Size Error: "File must be smaller than 25 MB. Current size: 35 MB"
    ```
  </Accordion>
</AccordionGroup>

### Runtime feedback

File upload buttons now provide feedback hints for success, progress, and error states. Previously, users lacked sufficient feedback when uploading a file unless they had a File Preview component or image link, making it difficult to know if the file was uploaded successfully or to see the progress.

<CardGroup>
  <Card title="Loading Overlay" icon="spinner">
    Optional overlay loader during file upload for both web and mobile
  </Card>

  <Card title="Toast Messages" icon="message">
    Success and error messages displayed as toasts at runtime, informing users about upload status
  </Card>

  <Card title="Dynamic Messages" icon="wand-magic-sparkles">
    Display dynamic values in toast and loading messages for context-aware feedback
  </Card>
</CardGroup>

#### Configuration properties

The following properties are available in the File Upload button configuration panel:

| Property                          | Description                                                      |
| --------------------------------- | ---------------------------------------------------------------- |
| **Loading behavior**              | Controls how the loading indicator appears (`NONE` or `OVERLAY`) |
| **Loading message**               | Custom message displayed during upload (supports dynamic values) |
| **Toast notification on success** | Toggle to show success toast when upload completes               |
| **Success message**               | Custom success message (supports dynamic values)                 |
| **Toast notification on error**   | Toggle to show error toast when upload fails                     |
| **Error message**                 | Custom error message (supports dynamic values)                   |

#### Configuring upload feedback

<AccordionGroup>
  <Accordion title="Loading Behavior" icon="spinner">
    Configure how loading indicators appear during file uploads:

    | Option      | Description                                                   |
    | ----------- | ------------------------------------------------------------- |
    | **NONE**    | No loading overlay displayed                                  |
    | **OVERLAY** | Full-screen overlay with spinner and optional loading message |

    **Loading Message Configuration**:

    * Configure custom messages using substitution tags or dynamic values
    * Works consistently across web and mobile platforms

    **Example messages**:

    * "Uploading your document..."
    * "Processing \$..."
    * "Please wait while we upload your file"
  </Accordion>

  <Accordion title="Success Messages" icon="circle-check">
    **Success Toast**: Displayed when the file upload completes successfully

    * **Enable**: Toggle "Toast notification on success" to show the toast
    * **Custom message**: Set a personalized success message with dynamic values
    * **Auto-dismiss**: Toast automatically disappears after 3-5 seconds

    **Example messages**:

    * "File uploaded successfully!"
    * "\$ has been uploaded"
    * "Your document is ready for processing"
  </Accordion>

  <Accordion title="Error Messages" icon="circle-xmark">
    **Error Toast**: Displayed when the file upload fails

    * **Enable**: Toggle "Toast notification on error" to show the toast
    * **Custom message**: Set a personalized error message with dynamic values
    * **Auto-dismiss**: Toast automatically disappears after 3-5 seconds

    **Example messages**:

    * "Upload failed. Please try again."
    * "Unable to upload \$. Check your connection."
    * "File upload error. Please select a different file."
  </Accordion>
</AccordionGroup>

<Tip>
  Use substitution tags and dynamic values in your loader and toast messages to provide contextual feedback that includes file names or other relevant data.
</Tip>

#### Theming

The loader and toast components inherit styling from your theme configuration:

<Tabs>
  <Tab title="Loader Styling">
    | Element            | Theme Property             |
    | ------------------ | -------------------------- |
    | Background color   | `general.appBackground`    |
    | Loading text color | `general.generalTextColor` |
    | Loading text style | `general.textFont`         |
    | Spinner tint color | `general.accentColor`      |
    | Dimmed background  | `rgba(0, 0, 0, 0.25)`      |
  </Tab>

  <Tab title="Toast Styling">
    | Toast Type    | Theme Property         |
    | ------------- | ---------------------- |
    | Success toast | `Message.fill.success` |
    | Error toast   | `Message.fill.error`   |
  </Tab>
</Tabs>

#### Custom loader API (SDK)

For advanced customization, developers can provide custom loader components through the SDK. The `customLoader` object supports file upload loaders alongside existing process loaders:

```typescript theme={"system"}
type CustomLoaders = {
  startProcess?: Component,    // Loader for process start
  reloadProcess?: Component,   // Loader for process reload
  defaultUpload?: Component,   // Default loader for file uploads
  defaultAction?: Component,   // Default loader for actions
  actions?: Record<string, Component>  // Named action loaders
}
```

**Loader resolution order:**

1. If a named action loader exists (`customLoader.actions?.[actionName]`), use it
2. Otherwise, if `defaultAction` or `defaultUpload` is defined, use that
3. Fall back to the internal SDK loader

<Info>
  Custom loaders allow you to maintain consistent branding and UX patterns across your application while leveraging the FlowX upload infrastructure.
</Info>

### File upload example

Example configuration for an image upload button:

<Frame>
  ![File upload example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/file_upload_img.png)
</Frame>

**Configuration Details**:

* **Accepted Types**: `image/*` (all image formats)
* **Max Size**: 5 MB
* **Error Handling**: Custom messages for type and size violations
* **UI Feedback**: Progress indication and preview capabilities

### File upload actions

<Info>
  The File Upload Button only supports the **Upload** action type. For multi-file uploads, see the [Multiple File Upload](./multiple-file-upload) component.
</Info>

<AccordionGroup>
  <Accordion title="Event Configuration" icon="bolt">
    **Event Type**: CLICK (same as basic buttons)

    **Action Types for File Upload**:

    * **File Processing**: Validate, resize, or convert files
    * **Progress Tracking**: Show upload progress and status
    * **Data Integration**: Process file content into application data
    * **Workflow Advancement**: Continue process after successful upload

    <Frame>
      ![File upload action configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/file_upload_action.png)
    </Frame>
  </Accordion>

  <Accordion title="Multi-file uploads" icon="gears">
    The File Upload Button handles **single-file uploads** only. For batch uploads with drag-and-drop, file validation, and progress tracking, use the dedicated [Multiple File Upload](./multiple-file-upload) component.
  </Accordion>
</AccordionGroup>

### File upload styling

File upload buttons have specialized styling options:

<Tabs>
  <Tab title="Button Types">
    | Type      | Appearance           | Best Used For            |
    | --------- | -------------------- | ------------------------ |
    | **Fill**  | Solid background     | Primary upload actions   |
    | **Ghost** | Outlined style       | Secondary upload options |
    | **Text**  | Text-only appearance | Subtle upload links      |
  </Tab>

  <Tab title="Icon & Layout">
    **Icon Integration**: Same as basic buttons

    * **Icon Key**: Select from Media Library
    * **Icon Position**: Left, Right, or Center
    * **Icon Color**: Customizable appearance

    **Recommended Icons**:

    * Upload arrow (↑)
    * Cloud upload (☁↑)
    * Folder or document icons
    * Plus (+) for add file actions
  </Tab>

  <Tab title="Responsive Sizing">
    | Option    | Behavior                   | Use Case                 |
    | --------- | -------------------------- | ------------------------ |
    | **Fill**  | Expands to container width | Full-width upload areas  |
    | **Fixed** | Maintains specific width   | Consistent button sizing |
    | **Auto**  | Adjusts to content         | Compact layouts          |
  </Tab>
</Tabs>

## Best practices

<CardGroup>
  <Card title="Accessibility" icon="universal-access" href="../../../platform-deep-dive/accessibility">
    * Use descriptive labels that explain the button's purpose
    * Ensure sufficient color contrast for all button states
    * For icon-only buttons, set an accessibility label in the UI Designer

    See the [Accessibility guide](../../../platform-deep-dive/accessibility) for keyboard navigation, ARIA mapping, and screen reader details.
  </Card>

  <Card title="User Experience" icon="user">
    * Place primary actions prominently and consistently
    * Use loading states for actions that take time
    * Provide clear feedback for successful/failed actions
    * Group related buttons logically
    * Avoid too many competing call-to-action buttons
    * Consider touch targets for mobile users (minimum 44px)
  </Card>

  <Card title="Visual Design" icon="palette">
    * Maintain consistent button styling across the application
    * Use button hierarchy to guide user attention
    * Choose icons that are universally understood
    * Test button visibility in different lighting conditions
    * Consider color-blind users when relying on color alone
    * Ensure buttons look clickable and interactive
  </Card>

  <Card title="Performance" icon="gauge">
    * Optimize file upload handling for large files
    * Implement proper error handling and retry mechanisms
    * Provide progress feedback for long-running actions
    * Cache frequently used icons and styling
    * Test button responsiveness under load
    * Consider offline scenarios for critical actions
  </Card>
</CardGroup>

## Common use cases

### Basic button scenarios

| Use Case             | Button Type | Icon Suggestion | Action Type         |
| -------------------- | ----------- | --------------- | ------------------- |
| **Form Submission**  | Primary     | ✓ (checkmark)   | Process advancement |
| **Cancel Operation** | Secondary   | ✕ (close)       | Navigation back     |
| **Delete Item**      | Ghost       | 🗑 (trash)      | Data operation      |
| **View Details**     | Text        | 👁 (eye)        | Navigation          |
| **Save Draft**       | Secondary   | 💾 (save)       | Data operation      |

### File upload scenarios

| Use Case            | File Types        | Size Limit | Validation Notes              |
| ------------------- | ----------------- | ---------- | ----------------------------- |
| **Profile Photo**   | `image/*`         | 5 MB       | Square aspect ratio preferred |
| **Document Upload** | `.pdf,.doc,.docx` | 25 MB      | OCR processing available      |
| **Data Import**     | `.csv,.xlsx`      | 50 MB      | Column validation required    |
| **Media Gallery**   | `image/*,video/*` | 100 MB     | Thumbnail generation          |
| **Backup Files**    | `.zip,.rar`       | 500 MB     | Virus scanning enabled        |

## Platform considerations

<Tabs>
  <Tab title="Web Applications">
    **Enhanced Features**:

    * Drag and drop file upload support
    * Keyboard shortcuts for common actions
    * Hover states and advanced animations
    * Context menus for additional options
    * Multi-file selection capabilities
  </Tab>

  <Tab title="Mobile Applications">
    **Mobile Optimizations**:

    * Touch-friendly button sizes (minimum 44px)
    * Native file picker integration
    * Camera access for image uploads
    * Simplified button layouts for smaller screens
    * Gesture-based interactions
  </Tab>

  <Tab title="Cross-Platform">
    **Consistency Features**:

    * Shared styling configurations
    * Platform-appropriate animations
    * Adaptive button sizing
    * Consistent behavior patterns
    * Universal icon meanings
  </Tab>
</Tabs>


# Chat
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/chat

Enable interactive AI agent conversations with end-users through a conversational interface in FlowX applications.

The Chat component provides a conversational interface for AI-powered interactions. It enables real-time messaging between users and AI agents within your FlowX applications.

<Frame>
  <video />
</Frame>

## Overview

<CardGroup>
  <Card title="Real-time messaging" icon="bolt">
    Send and receive messages instantly with streaming support
  </Card>

  <Card title="AI agent integration" icon="robot">
    Connect to workflows powered by AI agents
  </Card>

  <Card title="Session management" icon="id-badge">
    Automatic session handling and persistence across page refreshes
  </Card>

  <Card title="Customizable UI" icon="palette">
    Themeable components with independent styling for agent and user messages
  </Card>
</CardGroup>

## Adding to a UI Flow

<Steps>
  <Step title="Navigate to UI Flows">
    Open your project and go to **UI Flows** from the left navigation menu.
  </Step>

  <Step title="Select or create a UI Flow">
    Select an existing UI flow or create a new one.

    <Frame>
      ![UI Flows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat1.png)
    </Frame>
  </Step>

  <Step title="Open UI Assets panel">
    In the left sidebar, expand the **UI Assets** panel. Find Chat alongside Table, Collection, and other components.

    <Frame>
      ![UI Assets](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat2.png)
    </Frame>
  </Step>

  <Step title="Add and configure">
    Drag **Chat** onto the canvas, then configure properties in the right panel.
  </Step>
</Steps>

***

## Configuration

### Required settings

| Property             | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| **Workflow**         | The agent workflow that handles chat interactions (required)  |
| **Welcome Message**  | Initial greeting shown when chat opens                        |
| **Thinking Message** | Text displayed while agent processes (default: "Thinking...") |

### Component hierarchy

The Chat component has configurable sub-components:

```
📁 Chat
  ├── 📄 Header (title, subtitle, new chat button)
  ├── 📁 Messages
  │     ├── 💬 Agent Message (avatar, text styling)
  │     ├── 💬 User Message (bubble styling)
  │     └── 💡 Suggested Prompts (pre-configured prompt suggestions)
  └── ⌨️ Input (placeholder, send button)
```

<Frame>
  ![Chat Component Anatomy](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat_anatomy.png)
</Frame>

### Settings by sub-component

<AccordionGroup>
  <Accordion title="Chat (root)" icon="comments">
    | Property             | Description                                              |
    | -------------------- | -------------------------------------------------------- |
    | **Workflow**         | Select the workflow handling chat interactions           |
    | **Welcome Message**  | Initial greeting (supports variables: `${customerName}`) |
    | **Thinking Message** | Text shown during processing                             |

    <Frame>
      ![Chat Component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Header" icon="window-maximize">
    | Property           | Description                   |
    | ------------------ | ----------------------------- |
    | **Button Label**   | "New chat" button text        |
    | **Title**          | Main header text              |
    | **Subtitle**       | Secondary text below title    |
    | **Show Chat Icon** | Toggle avatar icon visibility |
    | **Show Separator** | Toggle separator line         |

    <Frame>
      ![Header](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat_header.png)
    </Frame>
  </Accordion>

  <Accordion title="Chat History" icon="clock-rotate-left">
    | Property  | Description                                 |
    | --------- | ------------------------------------------- |
    | **Title** | Heading displayed on the chat history panel |
  </Accordion>

  <Accordion title="Agent Message" icon="robot">
    | Property        | Description                    |
    | --------------- | ------------------------------ |
    | **Show Avatar** | Toggle agent avatar visibility |

    <Frame>
      ![Agent Message](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/agent_message.png)
    </Frame>
  </Accordion>

  <Accordion title="Input" icon="keyboard">
    | Property               | Description                                                  | Default |
    | ---------------------- | ------------------------------------------------------------ | ------- |
    | **Placeholder**        | Hint text (e.g., "Ask me anything...")                       | —       |
    | **Enable Voice Input** | Show the microphone button so users can send voice messages. | `Off`   |

    <Frame>
      ![Input](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/input_message.png)
    </Frame>

    For runtime behavior (recording limits, playback rules) see [Voice input](/5.9/ai-platform/chat-component#voice-input) in the Chat component reference.
  </Accordion>

  <Accordion title="Suggested Prompts" icon="lightbulb">
    Displays pre-configured prompt suggestions before the user types. Child of **Messages** (alongside Agent Message and User Message).

    | Property    | Type      | Default               | Description                                           |
    | ----------- | --------- | --------------------- | ----------------------------------------------------- |
    | **Title**   | string    | `"Suggested Prompts"` | Heading text displayed above the suggestions          |
    | **Prompts** | string\[] | —                     | List of prompt strings shown as clickable suggestions |

    Clicking a suggestion sends it as the user's message. Long prompts are truncated and revealed via tooltip.
  </Accordion>
</AccordionGroup>

***

## Styling

Configure visual styling through **Theme Admin** (Design Assets → Themes → Components → Chat).

### Themeable elements

| Element               | Key properties                                        |
| --------------------- | ----------------------------------------------------- |
| **Chat container**    | Padding, border, background, shadow                   |
| **Header**            | Title/subtitle text styles, separator                 |
| **Messages area**     | Padding, gap between messages                         |
| **Agent Message**     | Avatar icon, text style, background                   |
| **User Message**      | Bubble border, radius, background, text               |
| **Suggested Prompts** | Title text style, prompt chip appearance, hover state |
| **Input area**        | Border, background, send icon                         |

<Tip>
  All styling can be configured in Theme Admin for consistent branding. Changes preview in real-time.
</Tip>

***

## Display modes

<Info>
  The Chat component supports four display modes, including mobile chat and per-mode theme configuration.
</Info>

When adding a Chat component, you select a display mode that controls how the chat renders and where it can be placed.

| Display mode   | Description                                                | Placement                      |
| -------------- | ---------------------------------------------------------- | ------------------------------ |
| **Inline**     | Renders in place within the page layout (default)          | Child of any container or card |
| **Overlay**    | Positioned overlay panel with minimize and expand controls | Child of Page or Root Zone     |
| **FullScreen** | Takes over the full viewport                               | Child of Page or Root Zone     |
| **Floating**   | Floating panel triggered by a FAB (Floating Action Button) | Child of Page or Root Zone     |

<Info>
  You can change the display mode after creation if needed.
</Info>

<Warning>
  **Placement constraints:** Inline is only available when the parent is a **Container** or **Card**. Overlay, FullScreen, and Floating are only available when the parent is a **Page** or **Root Zone**. Unavailable options are disabled in the selection dialog.
</Warning>

### Sizing defaults

| Display mode   | Default width   | Default height  | Notes                                |
| -------------- | --------------- | --------------- | ------------------------------------ |
| **Inline**     | Fill (parent)   | Fill (parent)   | Supports Fill or Fixed sizing        |
| **Overlay**    | Configurable    | Configurable    | Positioned over content              |
| **FullScreen** | Full viewport   | Full viewport   | No sizing controls                   |
| **Floating**   | `420px` (fixed) | `640px` (fixed) | FAB at `right: 24px`, `bottom: 24px` |

<Tip>
  For Inline, you can switch between **Fill** and **Fixed** sizing for both width and height. For Floating, width and height are fixed values you can customize in the style panel.
</Tip>

### Floating action button (FAB)

Floating and FullScreen modes include a **Floating Action Button** that triggers the chat. The FAB is configurable in the style panel:

| Property     | Default                       | Description              |
| ------------ | ----------------------------- | ------------------------ |
| **Width**    | `56px`                        | FAB button width         |
| **Height**   | `56px`                        | FAB button height        |
| **Position** | Right: `24px`, Bottom: `24px` | Fixed position on screen |

### Theming per display mode

Theme values are configured independently per display mode and per platform (Web, Android, iOS) through **Design Assets → Themes → Components → Chat**. Supported properties include padding and margin for each mode.

For complete runtime details, see the [Chat component reference](/5.9/ai-platform/chat-component#display-modes).

***

## Advanced documentation

For comprehensive documentation including runtime behavior, session management, custom persistence workflows, SDK integration, and troubleshooting:

<Card title="Chat component - Full reference" icon="book" href="/5.9/ai-platform/chat-component">
  Complete technical documentation in AI Platform section
</Card>

## Related resources

<CardGroup>
  <Card title="Chat interface concepts" href="/5.9/ai-platform/using-agents/chat-interface" icon="comments">
    High-level chat integration patterns
  </Card>

  <Card title="AI Triggers" href="/5.9/ai-platform/conversational-workflows#ai-triggers" icon="bullseye">
    Launch conversational workflows with structured trigger messages
  </Card>

  <Card title="Knowledge bases" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview" icon="database">
    Ground AI responses in your data
  </Card>

  <Card title="AI in FlowX" href="/5.9/ai-platform/ai-in-flowx" icon="robot">
    AI capabilities overview
  </Card>
</CardGroup>


# File preview
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview

Preview file contents inside a UI flow without fully opening the file, using the File Preview component.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview.gif)
</Frame>

File preview UI elements offer various benefits such as conveying information, improving the aesthetic appeal of an interface, providing visual cues and feedback or presenting complex data or concepts in a more accessible way.

## Configuring a File preview element

A File Preview element can be configured for both mobile and web applications.

### File preview properties (web)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/file_preview_info.png)
</Frame>

The settings for the File Preview element include the following properties:

* **Title**: Specifies the title of the element. If the file is downloaded or shared, the file name should serve as the title used in the preview component.
* **Subtitle**: Allows for the inclusion of a subtitle for the element.
* **Display mode**: Depending on the selected display method, the following properties are available:
  * **Inline** → **Has accordion**:
    * `false`: Displays the preview inline without an expand/collapse option.
    * `true` (Default View: Collapsed): Displays the preview inline with an expand/collapse option, initially collapsed.
    * `true` (Default View: Expanded): Displays the preview inline with an expand/collapse option, initially expanded.

  * **Modal** → view icon is enabled
* **Has accordion**:  Introduces a Bootstrap accordion, facilitating the organization of content within collapsible items. It ensures that only one collapsed item is displayed at a time.
* **Source Type**:
  * **Media Library**: Refers to PDF documents uploaded in the Media Library.

<Info>
  PDF documents uploaded to the Media Library must adhere to a maximum file size limit of 10 MB.
</Info>

* **Process Data**: Identifies the key location within the process where the document is sourced, establishing the linkage between the document and process data.
* **Static**: Denotes the document's URL, serving as a fixed reference point.

<Warning>
  It's worth noting that the inline modal view can raise accessibility issues if the file preview's height exceeds the screen height.
</Warning>

### File preview properties (mobile)

<Check>
  Both iOS and Android devices support the share button.
</Check>

#### iOS

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_ios.gif)
</Frame>

#### Android

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_android.gif)
</Frame>

### File preview styling

The File Preview styling property enables you to customize the appearance of the element by adding valid CSS properties. For more information, see the [styling documentation](../../ui-designer/ui-designer#styling).

When drag and drop a File Preview element in UI Designer, it comes with the following default styling properties:

#### Sizing

* **Fit W** - auto
* **Fit H** - fixed / Height - 400 px

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_styling.png)
</Frame>

## File Preview example

Below is an example of a File Preview UI element with the following properties:

* **Display mode** - Inline
* **Has accordion** - True
* **Default view** - Expanded
* **Source Type** - Static

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_example.gif)
</Frame>


# Datepicker
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/datepicker-form-field

The datepicker (Calendar Picker) is a lightweight component that allows end users to enter or select a date value.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker_form_field.png)

The datepicker (Calendar Picker) is a lightweight component that allows end users to enter or select a date value.

<Info>
  The default datepicker value is `DD.MM.YYYY`.
</Info>

## Configuring the datepicker element

### Datepicker generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Datepicker styling**](#datepicker-styling)

#### Process data key

Process data key establishes the binding between the datepicker element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

#### Properties

* **Label**: The visible label for the datepicker element.
* **Placeholder**: Text that appears within the datepicker element when it is empty.
* **Min Date**: Set the minimum valid date selectable in the datepicker.
* **Max Date**: Set the maximum valid date selectable in the datepicker.
* **Min Date, Max Date error**: When a date is introduced by typing, define the error message to be displayed.
* **Helpertext**: Additional information about the datepicker element, which can be optionally hidden within an infopoint.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker1.png)

#### Datasource configuration

**Default Value**: The default values of the datepicker element, this will autofill the datepicker when you will run the process.

#### Validators

The following validators can be added to a datepicker: `required`, `custom`, `isSameOrBeforeToday` or `isSameOrAfterToday`. For more information, see the [validators documentation](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker2.png)

#### Hide/disable expressions

The datepicker behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the datepicker element when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the datepicker element when it returns a truthy value.

<Info>
  It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

#### Event handlers

Event handlers can be added to the datepicker element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the action type.

<Tip>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Tip>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker3.png)

### Datepicker settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the datepicker label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Datepicker styling

<Tabs>
  <Tab title="Web">
    #### Sizing

    Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

    * **fill**: Fills the available space.
    * **fixed**: Maintains a fixed width.
    * **auto**: Adjusts the width automatically based on content.
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.

    However, for mobile applications, there’s an additional sizing style property:

    * **Height** (pt - points): Determines the vertical size of the datepicker element on the screen.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.

    However, for mobile applications, there’s an additional sizing style property:

    * **Height** (dp - density-independent pixels): Determines the vertical size of the datepicker element on the screen.
  </Tab>
</Tabs>

#### Datepicker style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_all.png)
</Frame>

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width  **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_com_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color  **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Empty State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_empty_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Active State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_active_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Filled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_filled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_disabled_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Error State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ovselect_error_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Right icon color **\[COLOR]**
    * Left icon color **\[COLOR]**
    * Prefix/Suffix color **\[COLOR]**
    * Placeholder color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_hover-state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>


# Segmented button
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/segmented-button

It allows you to pick only one option from a group of options, and you can choose to have between 2 and 5 options in the group. The segmented button helps improve usability in your app.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/segmented_button1.gif)

## Configuring the segmented button

### Segmented button generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Segmented button styling**](#segmented-button-styling)

#### Process data key

Process data key establishes the binding between the segmented buton and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

#### Properties

* **Label**: The visible label for the segmented button.
* **Helpertext**: Additional information about the segmented button, which can be optionally hidden within an infopoint.

#### Datasource configuration

* **Default Value**: The default value of the segmented button (it can be selected from one of the static source values)
* **Source Type**: It is by default Static.
* **Add option**: Define label and value pairs here.

#### Validators

The following validators can be added to a segmented button: `required` and `custom`. For more information, see the [validators documentation](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/segmented_button_props.png)

#### Event handlers

Event handlers can be added to the segmented button element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the action type.

<Tip>
  For more information, see the [Event Handlers documentation](../../event-handlers).
</Tip>

### Segmented button settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the segmented button label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

<Tabs>
  <Tab title="Web">
    #### Sizing

    Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

    * **fill**: Fills the available space.
    * **fixed**: Maintains a fixed width.
    * **auto**: Adjusts the width automatically based on content.
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.
  </Tab>
</Tabs>

#### Segmented button style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)
</Frame>

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Border radius **\[TEXT]**
    * Border width  **\[TEXT]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_common.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color  **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Unselected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)
    </Frame>
  </Accordion>

  <Accordion title="Selected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled Unselected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled Selected State">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover Unselected State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_unselected_state.png)
    </Frame>
  </Accordion>

  <Accordion title="Hover Selected State (only for Web configuration)">
    * Border color **\[COLOR]**
    * Background color **\[COLOR]**
    * Text color **\[COLOR]**
    * Icon color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_selected_state.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>


# Slider
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/slider

It allows you to pick only one option from a group of options, and you can choose to have between 2 and 5 options in the group. The slider helps improve usability in your app.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/slider.gif)

## Configuring the slider element

### Slider generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource)
* [**Validators**](#validators)
* [**Expressions**](#expressions)
* [**Event handlers**](#event-handlers)
* [**Slider styling**](#slider-styling)

#### Process data key

Process data key establishes the binding between the slider element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node#from-integration).

#### Properties

* **Label**: The visible label for the slider element.
* **Show value label**: A toggle option that determines whether the current selected value of the slider is displayed as a label alongside the slider handle.
* **Helpertext**: Additional information about the slider element, which can be optionally hidden within an infopoint.
* **Min Value** : The minimum value or starting point of the slider's range, it defines the lowest selectable value on the slider.
* **Max Value**: The maximum value or end point of the slider's range, it sets the highest selectable value on the slider.
* **Suffix**: An optional text or symbol that can be added after the displayed value on the slider handle or value label, it is commonly used to provide context or units of measurement.
* **Step size**: The increment or granularity by which the slider value changes when moved, it defines the specific intervals or steps at which the slider can be adjusted, allowing users to make more precise or discrete value selections.

#### Datasource configuration

**Default Value**: The default value of the slider (static value - integer) the initial value set on the slider when it is first displayed or loaded, it represents a static value (integer), that serves as the starting point or pre-selected value for the slider, users can choose to keep the default value or adjust it as desired.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/slider_general.png)
</Frame>

#### Validators

The following validators can be added to a slider: `required` and `custom`. For more information, see the [validators documentation](../../validators).

#### Hide/disable expressions

* **Hide condition**: A JavaScript expression that hides the sloder element when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the slider element when it returns a truthy value.

<Info>
  It’s important to make sure that disabled fields have the same expression configured under the path expressions → hide.
</Info>

#### Event handlers

Event handlers can be added to the slider element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the action type. For more information, see the [Event Handlers documentation](../../event-handlers).

### Multiple sliders

You can also use multiple sliders UI elements that are interdependent, as you can see in the following example:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/multiple_sliders.gif)

<Info>
  You can improve the configuration of the slider using computed values as in the example above. These values provide a more flexible approach for handling complex use cases. You can find an example by referring to the following documentation:

  [**Dynamic & computed values**](../../dynamic-and-computed-values#computed-values)
</Info>

### Slider settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the slider label.
  * **Helpertext**: Override helper text/info point.
  * **Show value**: Override the show value option.
  * **Suffix**: Override the suffix.
* Expressions:
  * **Hide**: Override the hide expression.

<Tip>
  Overrides can always be imported/pushed from one platform to another:

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)
</Tip>

### Slider styling

<Tabs>
  <Tab title="Web">
    #### Sizing

    Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:

    * **fill**: Fills the available space.
    * **fixed**: Maintains a fixed width.
    * **auto**: Adjusts the width automatically based on content.
  </Tab>

  <Tab title="iOS">
    Similar styling considerations apply to iOS as for web.
  </Tab>

  <Tab title="Android">
    Similar styling considerations apply to Android as for web.
  </Tab>
</Tabs>

#### Slider style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)
</Frame>

Style options:

<AccordionGroup>
  <Accordion title="Common Properties">
    * Limits font **\[FONT]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_com_props.png)
    </Frame>
  </Accordion>

  <Accordion title="Label">
    * Default state
      * Text color **\[COLOR]**
    * Disabled state
      * Text color  **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)
    </Frame>
  </Accordion>

  <Accordion title="Helper">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**
    * Helper Tooltip
      * Text style **\[FONT]**
      * Text color **\[COLOR]**
      * Background color **\[COLOR]**
      * Icon Color **\[COLOR]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)
    </Frame>
  </Accordion>

  <Accordion title="Error">
    * Text color **\[COLOR]**
    * Text style **\[FONT]**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)
    </Frame>
  </Accordion>

  <Accordion title="Default state">
    * Empty **\[COLOR]**
    * Filled **\[COLOR]**
    * Knob color **\[COLOR]**
    * Limits **\[COLOR]**
    * Value **\[COLOR]**

    <Info>
      On iOS, overrides for the **Knob** are not available.
    </Info>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)
    </Frame>
  </Accordion>

  <Accordion title="Disabled State">
    * Empty **\[COLOR]**
    * Filled **\[COLOR]**
    * Knob color **\[COLOR]**
    * Limits **\[COLOR]**
    * Value **\[COLOR]**

    <Info>
      On iOS, overrides for the **Filled** and **Empty** states, as well as the **Knob**, are not available.
    </Info>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  You can import or push the overrides from one platform to another without having to configure them multiple times.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)
</Info>


# Image
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/image

Image UI elements are graphical components of a user interface that display a static or dynamic visual representation of an object, concept, or content.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_general.png)
</Frame>

These elements can be added to your interface using the UI Designer tool, and they are often used to convey information, enhance the aesthetic appeal of an interface, provide visual cues and feedback, support branding and marketing efforts, or present complex data or concepts in a more intuitive and accessible way.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_generic.png)
</Frame>

## Configuring an image

Configuring an image in the UI Designer involves specifying various settings and properties. Here are the key aspects of configuring an image:

### Image settings

The image settings consist of the following properties:

* **Source location** - the location from where the image is loaded:

  * [**Media Library**](#media-library)
  * [**Process Data**](#process-data)
  * [**External**](#external)

Depending on which **Source location** is selected, different configurations are available:

### Media library

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_media_library1.png)
</Frame>

* **Image key** - the key of the image from the media library
* **Select from media library** - search for an item by key and select it from the media library

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/search_item_by_key.png)
</Frame>

* **Upload to media library** - add a new item (upload an image on the spot)
  * **upload item** - supported formats: PNG, JPG, GIF, SVG, WebP; ❗️(maximum size - 1 MB)
  * **key** - the key must be unique and cannot be changed afterwards

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/upload_to_media_lib.png)
</Frame>

### Process data

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/process_data.gif)
</Frame>

* Identify the **Source Type**. It can be either a **URL** or a **Base 64 string**.
* Locate the data using the **Process Data Key**.
* If using a URL, provide a **Placeholder URL** for public access. This is the URL where the image placeholder is available.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/process_data_img.png)
</Frame>

### External

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_external.png)
</Frame>

* **Source Type**: it can be either a **URL** or a **Base 64 string**
* **Image source**: the valid URL of the image.
* **Placeholder URL**: the public URL where the image placeholder is available

## Event handlers

The event handlers property allows you to add an event handler, which must be configured on the same node. For more information, see the [Event Handlers documentation](../event-handlers).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_ui_actions.png#center)
</Frame>

## Image styling

The image styling property allows you to add or to specify valid CSS properties for the image. For more information, see the [styling documentation](../../ui-designer/ui-designer#styling).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_styling.png)
</Frame>


# Indicators
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/indicators

The indicators (Message UI elements) allow you to display different types of messages.

Messages can be categorized into the following types:

* **Info**: Used to convey general information to users.
* **Warning**: Indicates potential issues or important notices.
* **Error**: Highlights errors or critical issues.
* **Success**: Communicates successful operations or completion.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicators_gen.png)
</Frame>

## Properties

When configuring a message, you have the following properties:

* **Message**: The content of the message body, this property supports markdown attributes such as: bold, italic, bold italic, strikethrough and URLs, allowing you to format the content of the message.
* **Type**: as mentioned above, there are multiple indicators: info, warning, error, success
* **Expressions**: you can define expressions to control when the message should be hidden. This can be useful for dynamically showing or hiding messages based on specific conditions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicators_prop.png)

Info example with markdown:

```markdown theme={"system"}
If you are encountering any difficulties, please [contact our support team](mailto:support@flowx.ai).
```

When executed, will look like this:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicators1.png)

## Types and Usage

Here's how you can use the Message UI element in your UI design:

### Info

If you are encountering any difficulties, please [contact our support team](mailto:support@flowx.ai).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/info_indicator.png)
</Frame>

### Error

An error occurred while processing your request. Please try again later.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_error.png)
</Frame>

### Success

Your payment was successfully processed. Thank you for using our services!

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_success.png)
</Frame>

## Indicators styling

To create an indicator with specific styling, sizing, typography, and color settings, you can use the following configuration:

### Style

The Style section allows you to customize the appearance of your indicator UI element. You can apply the following style to achieve the desired visual effect:

* **Text**: Displays only the icon and the text.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_text.png)

* **Border**: Displays the icon, the text and the border.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_border.png)

* **Fill**: It will fill the UI element's area.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_fill.png)

<Tip>
  For more information, see the [styling documentation](../../ui-designer/ui-designer#styling).
</Tip>


# Markdown
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown

A UI component that renders Markdown-formatted content on a screen.

<Note>
  This is the standalone Markdown UI component. For Markdown rendering inside chat messages, see the [Chat](./chat) component.
</Note>

## Overview

Use a Markdown component when you need to display rich text that may include structure (headings, lists, tables) or content authored in Markdown by an AI model, a CMS entry, or a process data field. Common use cases:

* Surfacing an AI-generated explanation alongside a form
* Embedding Terms & Conditions or Help text written in Markdown
* Rendering a step-by-step instruction list pulled from CMS
* Showing a tabular summary returned by a workflow

The Markdown component is read-only. Bind its content to a process data key or a static value, and it renders on the fly.

## Properties

| Property            | Type                | Description                                                                                |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| **Content**         | String / expression | Markdown source. Bind to a process data key or set a static literal.                       |
| **Visibility**      | Expression          | JavaScript expression that hides the component when truthy.                                |
| **Theme overrides** | Object              | Override fonts, colours, link colour, heading styles, and table styling for this instance. |

## Supported Markdown

Standard CommonMark syntax: headings (`#` to `######`), bold/italic, links, ordered and unordered lists, fenced code blocks, inline code, blockquotes, and tables (GFM-style). Raw HTML is not rendered.

## Theme configuration

The Markdown component exposes two theme entries: **Markdown** (for the body) and **Markdown table** (for tables embedded inside Markdown content).

### Markdown — body defaults

| Token          | Default                           | Description           |
| -------------- | --------------------------------- | --------------------- |
| `font`         | `typography@Paragraph/P1#regular` | Base body typography. |
| `color`        | `color@shades#900`                | Body text colour.     |
| `linkColor`    | `color@primary#500`               | Inline link colour.   |
| `heading1Font` | `typography@Heading/H5#medium`    | H1 typography.        |
| `heading2Font` | `typography@Heading/H6#medium`    | H2 typography.        |
| `heading3Font` | `typography@Paragraph/P3#medium`  | H3 typography.        |
| `heading4Font` | `typography@Paragraph/P2#medium`  | H4 typography.        |
| `heading5Font` | `typography@Paragraph/P2#medium`  | H5 typography.        |
| `heading6Font` | `typography@Paragraph/P2#medium`  | H6 typography.        |

### Markdown table — defaults

| Token                   | Default                           | Description                    |
| ----------------------- | --------------------------------- | ------------------------------ |
| `borderColor`           | `color@neutrals#200`              | Outer table border colour.     |
| `dividerColor`          | `color@neutrals#200`              | Row and column divider colour. |
| `backgroundColor`       | `color@shades#0`                  | Cell background.               |
| `font`                  | `typography@Paragraph/P1#regular` | Cell typography.               |
| `color`                 | `color@shades#900`                | Cell text colour.              |
| `headerFont`            | `typography@Paragraph/P1#medium`  | Header row typography.         |
| `headerColor`           | `color@shades#900`                | Header row text colour.        |
| `headerBackgroundColor` | `color@neutrals#100`              | Header row background.         |

To override globally, edit **Theme → Components → Markdown** (and **Markdown table**) in the Designer.

## Related resources

<CardGroup>
  <Card title="UI Designer overview" icon="palette" href="../ui-designer">
    Compose screens in the UI Designer.
  </Card>

  <Card title="Typography" icon="font" href="./typography">
    Configure typography styles for text components.
  </Card>
</CardGroup>


# Multiple file upload
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload

A drag-and-drop upload component that lets users select and upload multiple files in a single action.

The Multiple File Upload component provides a drag-and-drop area where users can select multiple files and upload them in a single request. It is purpose-built for workflows that require batch document submission — such as onboarding packets, supporting evidence, or multi-page scans.

<Frame>
  ![Multiple file upload component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/multiple-file-upload-overview.png)
</Frame>

***

## Overview

Unlike the [File Upload Button](./buttons#file-upload-button), which handles one file at a time via a button click, the Multiple File Upload component offers:

<CardGroup>
  <Card title="Batch uploads" icon="files">
    Upload multiple files in a single request with individual validation per file
  </Card>

  <Card title="Drag and drop" icon="upload">
    Drag-and-drop zone with click-to-browse fallback
  </Card>

  <Card title="File management" icon="list-check">
    Preview selected files with name, size, and a remove option before uploading
  </Card>
</CardGroup>

**Platform availability:** React SDK (web) — since 5.5.0. Angular SDK (web) — since 5.8.0. Available in both process-based screens and UI Flows.

### UI Flow upload flow

When the component is bound to a UI Flow upload action:

1. The SDK uploads the selected files to the temp-file store via `POST /document/internal/wks/{workspaceId}/temp-files/upload-multiple` (multipart, document-plugin).
2. The SDK calls `POST /api/runtime/wks/{workspaceId}/appId/{appId}/ui-flow/{uiFlowSessionId}/upload-multiple` (process-engine) with the list of returned temp-file IDs. The 200 response returns a server-generated `uploadBatchId`.
3. process-engine sends a single bulk command to document-plugin; document-plugin persists each file in the session.
4. The SDK receives one SSE frame (`eventType=UI_FLOW_FILE_UPLOAD_MULTIPLE`, `namespace=uploadBatchId`) carrying the per-file results.
5. The per-file results are written to the action's `responseKey` as a list under the UI Flow session variables.

**UI Flow response shape:**

```json theme={"system"}
{
  "documents": [
    { "uploadResponseId": "...", "fileName": "...", "fileSize": 123, "errorMessage": null }
  ]
}
```

The UI Flow per-file shape (`UiFlowUploadResponse`) is a subset of the process-based upload response — it omits `customId`, `fileId`, `documentType`, `documentLabel`, and `status`, which are not meaningful for session-scoped uploads.

***

## Component properties

The following properties are available in the Multiple File Upload configuration panel:

### Display

| Property         | Key           | Description                        | Default                           |
| ---------------- | ------------- | ---------------------------------- | --------------------------------- |
| **Title**        | `title`       | Heading displayed in the drop zone | `"Drag & drop your files here"`   |
| **Subtitle**     | `subtitle`    | Supporting text below the title    | `"or click to browse your files"` |
| **Browse label** | `browseLabel` | Text on the browse button          | `"Browse Files"`                  |
| **Upload label** | `uploadLabel` | Text on the upload action button   | `"Upload Files"`                  |
| **Reset label**  | `resetLabel`  | Text on the remove/reset button    | `"Remove Files"`                  |

### Validation

| Property                        | Key                 | Description                                                                                      | Default | Required |
| ------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------ | ------- | -------- |
| **Accepted file types**         | `accept`            | Comma-separated MIME types, extensions, or wildcards (e.g., `png`, `application/pdf`, `image/*`) | —       | Yes      |
| **Invalid file type message**   | `invalidFileType`   | Error shown when a file does not match accepted types                                            | —       | Yes      |
| **Max files**                   | `maxFiles`          | Maximum number of files allowed per upload                                                       | —       | Yes      |
| **Max files exceeded message**  | `filesExceeded`     | Error shown when the file count exceeds the limit                                                | —       | Yes      |
| **Max files size**              | `maxFilesSize`      | Maximum total size of all files in bytes                                                         | —       | Yes      |
| **Files size exceeded message** | `filesSizeExceeded` | Error shown when total size exceeds the limit                                                    | —       | Yes      |

<Warning>
  All validation properties are required. You must configure accepted file types, max file count, and max file size along with their corresponding error messages.
</Warning>

### Feedback

| Property            | Key              | Description                                       | Default                                |
| ------------------- | ---------------- | ------------------------------------------------- | -------------------------------------- |
| **Show success**    | `showSuccess`    | Display a toast notification on successful upload | `false`                                |
| **Success message** | `successMessage` | Custom success toast text                         | `"Files successfully uploaded"`        |
| **Show error**      | `showError`      | Display a toast notification on upload failure    | `false`                                |
| **Error message**   | `errorMessage`   | Custom error toast text                           | `"There was an error with the upload"` |
| **Loading type**    | `loading`        | Loading indicator style (`Overlay` or `None`)     | `None`                                 |
| **Loading message** | `loadingMessage` | Text displayed during the upload                  | `"Files are being uploaded..."`        |

### Visibility

| Property               | Key        | Description                                                        |
| ---------------------- | ---------- | ------------------------------------------------------------------ |
| **Hide condition**     | `hide`     | Expression that hides the component when it evaluates to `true`    |
| **Disabled condition** | `disabled` | Expression that disables the component when it evaluates to `true` |

***

## Event handler configuration

The Multiple File Upload component only supports the **Upload** action type.

When configuring the event handler for this component, set:

* **Event type**: `CLICK`
* **Action type**: `Upload`

This links the component to an [Upload File action](../../actions/upload-file-action) configured on the node. The SDK automatically populates `{actionName}TempFileIds` (a list of UUIDs) in the process instance params before triggering the action.

<Info>
  Starting with 5.5.0, the existing [File Upload Button](./buttons#file-upload-button) is also adjusted so that **Upload** is its only selectable action type (matching this component). It continues to work with the single-file path (`{actionName}TempFileId`). Both components can coexist in the same process.
</Info>

***

## How it works

<Steps>
  <Step title="User selects files">
    The user drags files into the drop zone or clicks **Browse Files** to select them. Each file is validated against the configured accepted types, max files count, and max file size.
  </Step>

  <Step title="Files uploaded to temporary storage">
    When the user clicks **Upload Files**, the SDK sends all selected files in a single `multipart/form-data` request to the document plugin's bulk temp upload endpoint. The response returns a list of temporary file IDs.
  </Step>

  <Step title="Process action triggered">
    The SDK populates `{actionName}TempFileIds` with the list of temp file IDs and triggers the Upload File action. The process engine detects the list key and routes the request through the bulk Kafka path.
  </Step>

  <Step title="Documents persisted">
    The document plugin receives the bulk persist request, processes each file individually, and returns a response with per-file results (including partial success handling).
  </Step>
</Steps>

For the backend configuration details, see the [Upload File action](../../actions/upload-file-action) documentation and the [document upload scenario](../../../../platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document).

***

## Important behavior

<AccordionGroup>
  <Accordion title="Document type and storage" icon="folder-open">
    All files uploaded through this component share the same `customId` and use `documentType=BULK` with `shouldOverride=false`. This means:

    * Multiple files accumulate under the same `customId` — they are stored as separate documents, not as a single archive
    * **Re-uploading does not replace previous files** — it adds new ones alongside the existing documents
    * If you need to replace previously uploaded files, you must delete them separately before re-uploading
  </Accordion>

  <Accordion title="Validation scope" icon="shield-check">
    Validation runs **client-side before upload**:

    * **File type** — validated per file against the `accept` property
    * **File count** — validated against `maxFiles` (total selected files)
    * **Total size** — validated against `maxFilesSize` (sum of all file sizes)

    There is no per-file size limit in this component. Only the total size across all files is checked.
  </Accordion>

  <Accordion title="Upload feedback" icon="spinner">
    The component provides an overall loading state (overlay or none) during the upload. Individual per-file progress indicators are not available — the upload is treated as a single batch operation.

    After the upload completes, the component clears its state (file list), hides the loader, and shows a success or error toast (if configured).
  </Accordion>

  <Accordion title="File selection UX" icon="hand-pointer">
    Users can add files incrementally:

    * Drag and drop files into the zone multiple times
    * Click **Browse Files** multiple times to add more
    * Each selected file appears as a card showing file name and size
    * Individual files can be removed with the delete button before uploading
    * The **Remove Files** button clears all selected files at once
  </Accordion>
</AccordionGroup>

***

## Theming

The Multiple File Upload component supports full theming through Theme Admin. The component is registered under `contentWeb → components → bulkFileUpload`.

<Tabs>
  <Tab title="Drop zone">
    | Token                | Description                                     |
    | -------------------- | ----------------------------------------------- |
    | **Title font**       | Font style for the drop zone heading            |
    | **Title color**      | Color for the drop zone heading                 |
    | **Subtitle font**    | Font style for the subtitle text                |
    | **Subtitle color**   | Color for the subtitle text                     |
    | **Border width**     | Drop zone border width (inherits from general)  |
    | **Border radius**    | Drop zone corner radius (inherits from general) |
    | **Border color**     | Drop zone border color                          |
    | **Background color** | Drop zone background                            |
    | **Shadow**           | Drop zone shadow                                |
  </Tab>

  <Tab title="File items">
    | Token                  | Description                            |
    | ---------------------- | -------------------------------------- |
    | **File name font**     | Font style for the file name           |
    | **File name color**    | Color for the file name                |
    | **File size font**     | Font style for the file size text      |
    | **File size color**    | Color for the file size text           |
    | **File border width**  | Border width for individual file rows  |
    | **File border radius** | Corner radius for individual file rows |
    | **File border color**  | Border color for individual file rows  |
  </Tab>

  <Tab title="Caption">
    | Token             | Description                        |
    | ----------------- | ---------------------------------- |
    | **Caption font**  | Font style for helper/caption text |
    | **Caption color** | Color for helper/caption text      |
  </Tab>
</Tabs>

### Icons

The component uses three system icons that are included automatically via CMS migration:

| Icon key          | Description                                    |
| ----------------- | ---------------------------------------------- |
| `sys_BFUTitle`    | Icon displayed in the drop zone header         |
| `sys_BFUDocument` | Icon displayed next to each file in the list   |
| `sys_BFUDelete`   | Icon for the delete/remove button on each file |

### Substitution tags

The component also registers system substitution tags for localization and accessibility:

| Tag code                   | English             | Romanian                        |
| -------------------------- | ------------------- | ------------------------------- |
| `sys_bfu_max_files_size`   | Maximum files size: | Dimensiune maximă a fișierelor: |
| `sys_a11y_bfu_drop_files`  | Drop files          | Plasează fișierele              |
| `sys_a11y_bfu_delete_file` | Delete file         | Șterge fișier                   |

These tags are automatically available after CMS migration and can be customized per language in the CMS.

***

## Related resources

<CardGroup>
  <Card title="Upload file action" icon="upload" href="../../actions/upload-file-action">
    Configure the backend action for single and multi-file uploads
  </Card>

  <Card title="Uploading a new document" icon="file-circle-plus" href="../../../../platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document">
    End-to-end document upload scenario with the document plugin
  </Card>

  <Card title="File Upload Button" icon="file-arrow-up" href="./buttons#file-upload-button">
    Single-file upload button component
  </Card>

  <Card title="File preview" icon="eye" href="./file-preview">
    Display uploaded documents inline
  </Card>
</CardGroup>


# Progress bar
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar

A UI component for visualizing progress or completion state on a screen.

## Overview

Use a Progress Bar when the user needs a quick visual answer to *"how far along?"* — for example, a multi-step onboarding flow, a long-running document upload, an order-fulfilment status, or a goal-tracking dashboard.

The Progress Bar is read-only. Bind its value to a process field or computed expression and it updates as the data changes.

## Properties

| Property            | Type                | Description                                                                           |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------- |
| **Value**           | Number / expression | The current progress value. Bind to a process data key or use a computed expression.  |
| **Min**             | Number              | Lower bound of the range. Defaults to `0`.                                            |
| **Max**             | Number              | Upper bound of the range. Defaults to `100`.                                          |
| **Visibility**      | Expression          | JavaScript expression that hides the bar when truthy.                                 |
| **Theme overrides** | Object              | Override `color`, `backgroundColor`, `height`, `borderRadius` for this instance only. |

The Progress Bar normalises `(value - min) / (max - min)` into the visual fill, so values outside the range are clamped.

## Process data binding

To drive the bar from process data, set **Value** to a process data key:

```javascript theme={"system"}
${application.upload.percentComplete}
```

For derived values, use an expression — for example, mapping a step index to a percentage in a 4-step flow:

```javascript theme={"system"}
${application.flow.currentStep} * 25
```

See [Dynamic and computed values](../dynamic-and-computed-values) for the full expression syntax.

## Theme configuration

Defaults from the platform theme:

| Token             | Default             | Description                                             |
| ----------------- | ------------------- | ------------------------------------------------------- |
| `color`           | `color@primary#500` | Fill colour of the completed portion.                   |
| `backgroundColor` | `color@primary#100` | Track colour for the unfilled portion.                  |
| `height`          | `8px`               | Bar thickness.                                          |
| `borderRadius`    | `4px`               | Corner radius applied to both fill and track.           |
| `borderColor`     | `color@shades#0`    | Outline colour. Hidden by default via `borderWidth: 0`. |
| `borderWidth`     | `0px`               | Set to `1` or higher to display the outline.            |

To override globally, edit **Theme → Components → Progress Bar** in the Designer.

## Related resources

<CardGroup>
  <Card title="UI Designer overview" icon="palette" href="../ui-designer">
    Compose screens in the UI Designer.
  </Card>

  <Card title="Dynamic and computed values" icon="function" href="../dynamic-and-computed-values">
    Bind component properties to process data.
  </Card>
</CardGroup>


# Separator
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/separator

A visual divider component used to group and separate UI content in screens.

## Overview

Use a Separator when you need a clear visual boundary between two regions of a screen — for example, between a form section and an action bar, between repeated rows in a list, or between groups of related fields. Unlike empty containers or padding, a Separator carries explicit meaning to the reader: "this is one section, this is another."

The Separator is allowed inside any container component (Card, Container, Collection) as well as inside chat layouts and process screens.

## Properties

| Property            | Type       | Description                                                                                                                    |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Visibility**      | Expression | JavaScript expression that hides the Separator when truthy.                                                                    |
| **Theme overrides** | Object     | Override `color`, `borderWidth`, or other theme tokens for this instance only. See the Conditional styling guide for examples. |

The Separator has no process-data binding — it is purely presentational.

## Theme configuration

Defaults from the platform theme:

| Token   | Default              | Description                                                                                      |
| ------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| `color` | `color@neutrals#200` | Line color. Override at the theme level for global changes, or per instance via theme overrides. |

To override the default for an entire workspace, edit the **Theme → Components → Separator** section in the Designer.

## Related resources

<CardGroup>
  <Card title="UI Designer overview" icon="palette" href="../ui-designer">
    Compose screens in the UI Designer.
  </Card>

  <Card title="Conditional styling" icon="wand-magic-sparkles" href="../conditional-styling">
    Apply dynamic styles and theme overrides.
  </Card>
</CardGroup>


# Table
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/table

The Table component is a versatile UI element allowing structured data display with customizable columns, pagination, filtering, and styling options.

## Overview

The **Table** component is available **only for Web**, built to deliver a consistent design through FlowX.AI’s theming framework. It closely mirrors the [**Collection**](./collection/collection) component functionality, offering dynamic data handling and flexible row/column configurations.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_overview.png)
</Frame>

<Info>
  **Web-only UI Component:** The Table component is designed specifically for web applications and includes theming options for consistent design across the platform.
</Info>

## Table elements

1. **Table Header (`th`)**\
   Displays column labels, typically one `th` element per column.

2. **Rows (`tr`)**\
   Each row represents a single data entry from the source array. Rows automatically repeat based on your data size.

3. **Cells**\
   Cells hold data points within each row. You can place multiple UI elements (text, image, link, buttons) inside a cell.

4. **Actions Column**\
   If you enable row deletion or editing, an actions column is automatically created to handle row-level features (delete icon, edit icon, etc.).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_actions_column.gif)
</Frame>

<Info>
  By default, when you create a new Table, three columns and a matching set of cell placeholders are generated automatically.
</Info>

## Configuring the table

When building a Table, you’ll primarily interact with:

* **Generic Settings** (source key, columns, table body, expressions, styling)
* **Cell-Specific Settings** (sorting, filtering, editing, validators)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_settings.png)
</Frame>

<Tip>
  Below is an example of a JavaScript business rule that populates the Table with mock data. The `users` array is assigned to `application.users`, which serves as the Table’s source.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/dynamic_table.png)

  <Accordion title="Business rule exmaple">
    ```js theme={"system"}
     users = [
        {
            "firstName": "John",
            "lastName": "Doe",
            "loanAmount": {
                "amount": 1000.00,
                "code": "USD"
            },
            "birthDate": "1985-01-01T00:00:00Z",
            "email": "john.doe@example.com"
        },
        {
            "firstName": "John",
            "lastName": "Does",
            "loanAmount": {
                "amount": 2000.00,
                "code": "USD"
            },
            "birthDate": "1985-02-01T00:00:00Z",
            "email": "john.does@example.com"
        },
        {
            "firstName": "Jane",
            "lastName": "Doe",
            "loanAmount": {
                "amount": 3000.00,
                "code": "USD"
            },
            "birthDate": "1985-03-01T00:00:00Z",
            "email": "jane.doe@example.com"
        },
        {
            "firstName": "Jane",
            "lastName": "Does",
            "loanAmount": {
                "amount": 4000.00,
                "code": "USD"
            },
            "birthDate": "1985-04-01T00:00:00Z",
            "email": "jane.does@example.com"
        },
        {
            "firstName": "Jim",
            "lastName": "Doe",
            "loanAmount": {
                "amount": 5000.00,
                "code": "USD"
            },
            "birthDate": "1985-05-01T00:00:00Z",
            "email": "jim.doe@example.com"
        },
        {
            "firstName": "Jim",
            "lastName": "Does",
            "loanAmount": {
                "amount": 6000.00,
                "code": "USD"
            },
            "birthDate": "1985-06-01T00:00:00Z",
            "email": "jim.does@example.com"
        },
        {
            "firstName": "Jake",
            "lastName": "Doe",
            "loanAmount": {
                "amount": 7000.00,
                "code": "USD"
            },
            "birthDate": "1985-07-01T00:00:00Z",
            "email": "jake.doe@example.com"
        },
        {
            "firstName": "Jake",
            "lastName": "Does",
            "loanAmount": {
                "amount": 8000.00,
                "code": "USD"
            },
            "birthDate": "1985-08-01T00:00:00Z",
            "email": "jake.does@example.com"
        },
        {
            "firstName": "Jill",
            "lastName": "Doe",
            "loanAmount": {
                "amount": 9000.00,
                "code": "USD"
            },
            "birthDate": "1985-09-01T00:00:00Z",
            "email": "jill.doe@example.com"
        },
        {
            "firstName": "Jill",
            "lastName": "Does",
            "loanAmount": {
                "amount": 10000.00,
                "code": "USD"
            },
            "birthDate": "1985-10-01T00:00:00Z",
            "email": "jill.does@example.com"
        },
        {
            "firstName": "Joe",
            "lastName": "Doe",
            "loanAmount": {
                "amount": 11000.00,
                "code": "USD"
            },
            "birthDate": "1985-11-01T00:00:00Z",
            "email": "joe.doe@example.com"
        },
        {
            "firstName": "Joe",
            "lastName": "Does",
            "loanAmount": {
                "amount": 12000.00,
                "code": "USD"
            },
            "birthDate": "1985-12-01T00:00:00Z",
            "email": "joe.does@example.com"
        }
    ];

    application = {
        "users": users
    };

    output.put("application", application);
    ```
  </Accordion>
</Tip>

<Info>
  When creating a table, three columns with one corresponding cells are added by default.
</Info>

### Table generic settings

The following generic settings are found in the Generic tab and apply to all platforms (Web, iOS, and Android):

* [**Source key**](#source-key)
* [**Columns**](#columns)
* [**Table body**](#table-body)
* [**Expressions**](#expressions)
* [**Table Styling**](#table-styling)

#### Source key

* Specify an array of objects (e.g., `application.users`), enabling dynamic row creation based on your data structure.
* Similar to the Collection component.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_source_key.png)
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/Screenshot%202024-10-15%20at%2019.22.32.png)
</Frame>

#### Columns

* Customize the Table’s columns: add, delete, rename, or reorder.
* Each column automatically includes a corresponding th (header cell) and td (body cell).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_columns.png)
</Frame>

#### Table body

* **Default Sorting**: Sortable option must be enabled for the selected column for default sorting to work.
  * **Column**: Select the desired column.
  * **Direction**: Set the sort direction (**Ascending** or **Descending**).
* **Pagination**: Control how data is displayed by configuring pagination or enabling scrolling.
  * **Page Size**: Set the maximum number of entries displayed per page.
* **Scrollable**: Disable pagination to enable continuous scrolling through data.
* **Deletable Rows**: Enable row deletion.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_body.png)
</Frame>

#### Hide condition

* Optionally hide the entire Table based on a JavaScript expression including the data key from another component.
* Useful for conditional flows (e.g., only show the Table if certain conditions are met).

**Demonstration**:

<Frame>
  <video />
</Frame>

***

## Feature highlights

### Default sorting

* **Enable default sorting** in table body settings.
* **Select the desired column** and **sort direction** (ascending by default).

<Check>
  Sortable option must be enabled for the selected column at **cell level** for default sorting to work.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/cell_sorting.png)
  </Frame>
</Check>

<Frame>
  <video />
</Frame>

### Pagination & scrolling

Define how many rows appear on each page using **Pagination** feature.

<Frame>
  <video />
</Frame>

* **Scrolling**: Disable pagination to allow continuous scrolling.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/disable_pagination.png)
</Frame>

### Editable rows

Enable row editing in **cell-level → column settings**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-23%20at%2017.04.39.png)
</Frame>

* Editing can be triggered by double-click or the dedicated Edit button icon.

<Check>
  Make sure each editable cell references a valid data model key to facilitate edit.
</Check>

* Edits are validated and saved row-by-row.

The editor type for each cell is automatically determined by the data model type of the column's key:

| Data Model Type          | Editor                 |
| ------------------------ | ---------------------- |
| String (default)         | Text input             |
| Integer, Float, Currency | Number input           |
| Boolean                  | Toggle switch          |
| Date/Time                | Date picker            |
| Enum                     | Single-select dropdown |

<Tip>
  For enum columns, the dropdown options are automatically loaded from the enumeration referenced in the data model. No additional configuration is needed — set the column's **Editable** toggle to ON and ensure the key references an ENUM data model type.
</Tip>

### Deletable rows

Toggle **Deletable** in Table settings to enable row deletion.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.15.17.gif)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-23%20at%2017.17.32.png)
</Frame>

<Tip>
  A delete icon will appear in the Actions column, removing the corresponding row from the data source.
</Tip>

### Filters

Mark columns as filterable to enable filtering icons.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-24%20at%2016.37.06.png)
</Frame>

* Filter type automatically matches the column data type (string, number, date, boolean, or currency).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-24%20at%2016.48.18.png)
</Frame>

<Tip>
  Filtering option is ideal for large data sets where quick column-based searches are necessary.
</Tip>

## Table styling

### Sizing

* **Fit Width**: By default, the Table stretches to occupy available width.
* **Fit Height**: Grows automatically based on content height.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/table_sizing.png)
</Frame>

<Tip>
  **Horizontal scrolling** kicks in automatically when the combined column widths exceed the table's container. Set columns to **Fixed** widths large enough that their sum overflows, and the table renders a horizontal scrollbar at the bottom. This is useful on mobile or narrow layouts where many columns can't fit at once.
</Tip>

### Cell styling

**Layout Options:**

* **Direction**: Horizontal (default).
* **Justify**: Space-around (evenly spaces elements within each cell).
* **Align**: Start (left-aligned).
* **Wrap**: Enables text wrapping.
* **Gap**: 8px spacing between cell elements.

**Column Style Options:**

* **Width Fit Options**:
  * **Fill**: Fills available container space.
  * **Fixed**: Keeps a fixed column width.
  * **Auto**: Adjusts column width to fit content.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/cell_styling.png)
</Frame>

* **User Resizable Columns**: Adjust column width by dragging the column edges in the header, enhancing customization.

<Frame>
  ![User Resizable Columns](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/2024-10-15%2019.37.13.gif)
</Frame>

This Table component enhances flexibility and offers a cohesive design, integrated with FlowX.AI’s theming framework for a consistent, web-optimized user experience.

## Table event handler

Append a saveData action to the table and configure the action’s custom keys with the same key used as source for the table, in order for the backend to take into consideration the updated array.

See [**User Task configuration**](#user-task-configuration) section for more details.

## Actions in table cells

When configuring actions within a Table component, each action is bound to a unique table item key, ensuring that interactions within each cell are tracked and recorded precisely.
The key allows the action to target specific rows and store results or updates effectively.

* **Table Item Save Key**:
  * This key is essential for identifying the exact cell or row where an action should be executed and saved.
  * It ensures that data within each cell remains distinct and correctly mapped to each table entry.
* **Custom Key for Data Saving**:
  * Important: To properly send the data from a selected cell/row to the backend, you must configure both a **Custom Key** (in your `SaveData` action) and a **Table Item Save Key** (in your column/cell configuration) using the same value.
  * Having only a `Table Item Save Key` is not sufficient to propagate the updated information. The matching **Custom Key** in the **SaveData** action tells the system which row/cell data to capture and transmit.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_item_save_key.png)
</Frame>

* **Supported Action Types** - Available actions include:
  * **Action**: Initiates predefined actions within the cell.
  * **Start Process Inherit**: Enables workflows inherited from process configurations to be triggered.
  * **Upload**: Allows file or data uploads directly within a table cell.
  * **External**: Used to create an action that will open a link in a new tab.

## User Task configuration

When configuring a screen in User Task containing table, you must configure the following node actions:

<Steps>
  <Step title="Configure SaveData Action">
    * The `SaveData` action must be:
      * **Manual**: Requires user initiation.
      * **Optional**: Not mandatory for task completion.
      * **Repeatable**: Can be executed multiple times.
    * **Execution Order Constraint**:
      * The `SaveData` action can only be executed **before** mandatory actions.
      * The UI is built by configurators to ensure the correct execution order of actions.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2014.58.14.png)
    </Frame>

    * Add an event handler to the table by assigning the previously created node action.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2015.01.16.png)
    </Frame>

    <Info>
      Add a custom key that is exactly the source key of the table so the platform knows where to save the edits applied in the table.
    </Info>
  </Step>

  <Step title="Add Another Manual and Mandatory Action">
    * An additional **manual** and **mandatory** action should be included.
    * This ensures that the **token remains within the user task** where the table is rendered.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2014.58.26.png)
    </Frame>
  </Step>

  <Step title="Add Another Action (Optional)">
    * You can add another node action if you want to assign an event handler to a table cell element (e.g, a text).
    * Assign the event handler to that particular element.
    * Make sure it is manual, optional and repeatable (can only be executed before mandatory actions).
  </Step>
</Steps>

## Common patterns

### Populate a table from an integration workflow

When your table data comes from an external API (via an integration workflow), the pattern is:

<Steps>
  <Step title="Run the integration workflow">
    Use a **Service Task** with a **Start Integration Workflow** action. The workflow calls your API and returns the response to a process key (e.g., `application.users`).
  </Step>

  <Step title="Send data to the UI">
    Add a **Send Data to User Interface** action on the same node (or a subsequent one) to push the data to the frontend:

    ```json theme={"system"}
    {
      "application": ${application}
    }
    ```
  </Step>

  <Step title="Configure the table source">
    Set the Table's **Source Key** to the same key (e.g., `application.users`). Rows are generated automatically from the array.
  </Step>
</Steps>

<Tip>
  The table source must be an array of objects. If your API returns a nested structure, use a business rule to extract the array before binding it to the table.
</Tip>

***

### Filter table data using form controls

The Table component has [built-in column filters](#filters) for per-column filtering. For **cross-component filtering** (e.g., dropdown selections that filter the entire table), use a business rule triggered by an event handler:

<Steps>
  <Step title="Add form controls (dropdowns, inputs) to your screen">
    Configure each dropdown with a process data key (e.g., `filter.status`, `filter.category`).
  </Step>

  <Step title="Create a business rule for filtering">
    Add a **manual, optional, repeatable** business rule action on the User Task node:

    ```javascript theme={"system"}
    var originalData = input.application.users;
    var selectedStatus = input.filter.status;

    var filtered = originalData.filter(function(item) {
        if (selectedStatus && item.status !== selectedStatus) return false;
        return true;
    });

    output.displayed = { "users": filtered };
    ```
  </Step>

  <Step title="Add an event handler on each dropdown">
    On each form control, add an event handler with:

    * **Event:** `CHANGE`
    * **Action Type:** `ACTION`
    * **Node Action Name:** your filter business rule

    This triggers the filter every time a dropdown value changes.
  </Step>

  <Step title="Point the table to the filtered data">
    Set the Table's **Source Key** to the filtered key (e.g., `displayed.users`) instead of the original data.
  </Step>
</Steps>

<Info>
  Keep the original data in a separate key (e.g., `application.users`) so you can reset filters by copying it back to the displayed key.
</Info>

***

### Reset table to original data

To add a "Reset filters" button, create another business rule that copies the original data back:

```javascript theme={"system"}
output.displayed = { "users": input.application.users };
output.filter = { "status": null, "category": null };
```

Attach this as an event handler (type `ACTION`) on a reset button.

***

## FAQs

<AccordionGroup>
  <Accordion title="What is the `table item key` used for in Table actions?">
    The `table item key` is essential for identifying specific rows and cells within a table. When actions are triggered in table cells, this key ensures that the action applies to the correct item, allowing data to be saved accurately in the intended cell or row. Without this key, actions may not track or save data correctly.
  </Accordion>

  <Accordion title="How does the Table component differ from Collection?">
    While the Table component shares structural similarities with Collection, it is tailored specifically for tabular data. Unlike Collection, it supports column customization, row pagination, built-in filtering/sorting, and in-place row editing, streamlining the handling of tabular data.
  </Accordion>

  <Accordion title="Can I use conditional styling in Table cells?">
    Yes. You can use [conditional styling](../../conditional-styling) to dynamically update cell or row styles based on conditions, such as highlighting critical items or overdue entries.
  </Accordion>

  <Accordion title="Does the Table component support nested tables?">
    No, nested tables (tables within other tables) are currently unsupported and are not planned for future updates. This limitation keeps the Table component optimized for its intended use without overcomplicating its structure.
  </Accordion>

  <Accordion title="What actions can I use within Table cells?">
    Table cells support various actions:

    * **Action**: Executes a predefined action within the cell.
    * **Start Process Inherit**: Triggers workflows based on inherited process configurations.
    * **Upload**: Allows direct file or data uploads within a cell.
      Each of these actions requires a `table item key` to ensure data accuracy.
  </Accordion>

  <Accordion title="How is pagination configured in the Table component?">
    Pagination can be customized to control the number of entries displayed per page. Alternatively, you can enable scrollable view mode by disabling pagination, which provides a continuous, scrollable data view.
  </Accordion>

  <Accordion title="Can I edit data directly within the Table cells?">
    Yes. Enable the **Editable** toggle on individual columns in cell-level settings. Editing is triggered by double-click or the Edit button. The editor type (text, number, date, toggle, or single-select dropdown) is automatically determined by the column's data model type. Edits are validated and saved row-by-row.
  </Accordion>

  <Accordion title="Are there specific data sources required for populating a Table?">
    Yes, the Table component requires a source in the form of an array of objects. The source allows the Table to dynamically populate cells based on the data structure, ensuring rows and columns align with your data set.
  </Accordion>

  <Accordion title="What if I need to add custom actions within the Table?">
    Custom actions can be configured using the UI Designer. Each action added to a cell will use the `table item key` to perform tasks such as saving edits, initiating workflows, or uploading files directly from the table.
  </Accordion>

  <Accordion title="Can I hide specific columns or rows based on conditions?">
    Yes, the Table component supports JavaScript expressions to control visibility dynamically. By setting up expressions, you can create conditions that hide certain columns or rows when specific criteria are met.
  </Accordion>
</AccordionGroup>


# Tooltip
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip

A UI component that displays additional context on hover or focus, with configurable icon and content.

## Overview

A Tooltip is a thin contextual hint anchored to an icon. Use it to explain a non-obvious field label, surface a regulatory disclaimer next to a control, or expand on an acronym without taking screen space.

The icon is configurable from the theme, the trigger is hover or focus, and the overlay positions itself automatically to stay on screen.

The Tooltip is allowed inside any container component (Card, Container, Collection) as well as inside chat layouts and process screens.

## Properties

| Property            | Type                | Description                                                                                           |
| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| **Content**         | String / expression | Tooltip text. Bind to a process data key for dynamic content, or set a static literal.                |
| **Visibility**      | Expression          | JavaScript expression that hides the Tooltip when truthy.                                             |
| **Theme overrides** | Object              | Override icon, colours, font, padding, border, max-width, max-rows, or shadow for this instance only. |

## Process data binding

To drive Tooltip content from process data, bind **Content** to a process data key:

```javascript theme={"system"}
${application.help.fieldExplanation}
```

For static content, set **Content** to a string literal — for example, `"Your IBAN is shown as it appears on your bank statement."`.

See [Dynamic and computed values](../dynamic-and-computed-values) for the full expression syntax.

## Theme configuration

Defaults from the platform theme:

| Token                                                        | Default                      | Description                                                   |
| ------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------- |
| `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` | `8px` each                   | Inner padding around the tooltip content.                     |
| `font`                                                       | `typography@Caption#regular` | Body typography.                                              |
| `color`                                                      | `color@neutrals#500`         | Text colour.                                                  |
| `backgroundColor`                                            | `color@shades#100`           | Tooltip background.                                           |
| `borderColor`                                                | `color@neutrals#200`         | Outline colour.                                               |
| `borderWidth`                                                | `1px`                        | Outline thickness.                                            |
| `borderRadius`                                               | `8px`                        | Corner radius.                                                |
| `maxWidth`                                                   | `360px`                      | Maximum overlay width before text wraps.                      |
| `maxRows`                                                    | `5`                          | Maximum text rows before truncation.                          |
| `iconColor`                                                  | `color@neutrals#500`         | Trigger icon colour.                                          |
| `shadow`                                                     | `shadow@s`                   | Drop shadow on the overlay.                                   |
| `tooltipIcon` (icon)                                         | `sys_TooltipInfo_16`         | Trigger icon. Replace via the theme to use a different glyph. |

To override globally, edit **Theme → Components → Tooltip** in the Designer.

## Related resources

<CardGroup>
  <Card title="UI Designer overview" icon="palette" href="../ui-designer">
    Compose screens in the UI Designer.
  </Card>

  <Card title="Conditional styling" icon="wand-magic-sparkles" href="../conditional-styling">
    Apply dynamic styles to UI components.
  </Card>
</CardGroup>


# Typography
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/typography

Typography is an important aspect of design that greatly influences how users perceive and interact with your content. In this section, we'll explore how to effectively utilize two essential UI elements, "Text" and "Link."

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/typography_gen.png)

## Text

The "Text" UI element serves as a tool dedicated solely to presenting text within your user interface. Whether it's paragraphs or descriptions, the "Text" UI element. Through manipulation of embedded CSS properties, you're afforded to edit the visual appearance and formatting of text, aligning it with your design preferences.

### Markdown compatibility

The Text UI element gives you with the flexibility of Markdown formatting. You can enhance your text using various markdown tags, including:

* **Bold**

```markdown theme={"system"}
**Bold**
```

* *italic*

```markdown theme={"system"}
*italic*
```

* ***bold italic***

```markdown theme={"system"}
***bold italic***
```

* strikethrough

```markdown theme={"system"}
~~strikethrough~~
```

* URL

```markdown theme={"system"}
[URL](https://url.net)
```

* Inline code

```markdown theme={"system"}
Press `Enter` to continue
```

* Line break (use a raw `<br>` tag — Markdown blank lines and trailing spaces do **not** produce breaks)

```html theme={"system"}
First line.<br>Second line.
```

Let's take the following markdown text example:

```markdown theme={"system"}
Be among the *first* to receive updates about our **exciting new products** and releases. Subscribe [here](flowx.ai/newsletter) to stay in the loop! Do not ~~miss~~ it!
```

When running the process it will be displayed like this:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/text_markdown.png)

<Warning>
  The Text element renders inline-only Markdown. The following Markdown features are **not supported** and will appear as plain text:

  * Bullet lists (`- item`) and ordered lists (`1. item`)
  * Headings (`#`, `##`, `###`)
  * Paragraph breaks (a blank line between paragraphs)
  * Code blocks (triple backticks)
  * Blockquotes (`>`)
  * Tables
</Warning>

<Tip>
  **Need bullet points?** Stack multiple Text elements vertically inside a Container, or use a list-capable component instead of Text.

  **Need multi-line content?** Use a `<br>` tag between lines (shown above). Markdown blank lines and trailing spaces do not produce a line break.
</Tip>

### Text styling

The Styling section provides you with granular control over how your text is displayed, ensuring it aligns with your design vision.

#### Spacing:

Adjust the spacing around your text, setting the margin as follows: 16px 0 0 0 0 0 0 16px.

#### Sizing:

Choose "Fit W" to ensure the text fits the width of its container.

#### Typography

Define the font properties:

* **Font family**: Choose the desired font family.
* **Font weight**: Define the thickness of the font.
* **Font size**: Specify the font size in pixels (px).
* **Height**: Set the line height in pixels (px).
* **Color**: Determine the text color.

#### Align

Determine the text alignment.

## Link

Links are essential for navigation and interaction. The "Link" UI element creates clickable text that directs users to other pages or external resources.

### Configuring the Link element

The Link component provides a simple way to create hyperlinks in your application interface.

#### Properties

* **Label**: The visible text for the link that users will click on.
* **URL**: The destination URL for the link. This property supports:
  * Static URLs (e.g., `https://example.com`)
  * Dynamic keys for dynamic URL construction (e.g., `${application.externalUrl}`)
  * Combination of static text and dynamic values (e.g., `https://example.com/${application.userId}/profile`)

<Info>
  The Link component supports dynamic keys in the URL property across all platforms (Web, iOS, and Android). This allows you to dynamically construct URLs using process data stored in the datastore.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)
  </Frame>
</Info>

#### Using dynamic keys in URL

You can reference process data in your link URLs by using the `${key}` syntax:

**Example:**

If you have process data like:

```json theme={"system"}
{
  "application": {
    "documentId": "12345",
    "userId": "user-abc"
  }
}
```

You can create a link with:

* URL: `https://docs.example.com/view/${application.documentId}`
* Label: View Document

When rendered, this will create a link to `https://docs.example.com/view/12345`.

#### Link behavior

* Links open in a new browser tab by default
* The link text can be styled using the standard typography styling options
* Links maintain accessibility standards with proper hover and focus states

### Link styling

The Link element supports styling customization similar to the Text element:

#### Typography

* **Font family**: Choose the desired font family
* **Font weight**: Define the thickness of the font
* **Font size**: Specify the font size in pixels (px)
* **Color**: Determine the link color (default and hover states)

#### Spacing

Adjust the spacing around your link element using margin properties.


# Validators
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/validators

Apply pre-defined validation rules to form inputs such as text, number, email, and date fields across web, mobile, and desktop apps.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/validators.png)
</Frame>

FlowX.AI provides default validators such as:

## Predefined validators

<AccordionGroup>
  <Accordion title="min validator">
    This validator checks whether a numeric value is smaller than the specified value. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a required validator.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_min.png)
    </Frame>

    <Card title="min validator" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/min">
      Refer to MDN documentation for more details about the min attribute.
    </Card>
  </Accordion>

  <Accordion title="max validator">
    This validator checks whether a numeric value is larger than the specified value. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#required-validator) validator.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_max.png)
    </Frame>

    <Card title="max validator" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max">
      Refer to MDN documentation for more details about the max attribute.
    </Card>
  </Accordion>

  <Accordion title="minLength">
    This validator checks whether the input value has a minimum number of characters. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a required validator.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_minlength.png)
    </Frame>

    <Card title="minLength" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/minlength">
      Refer to MDN documentation for more details about the minlength attribute.
    </Card>
  </Accordion>

  <Accordion title="maxLength">
    This validator checks whether the input value has a maximum number of characters. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#required-validator) validator.

    <Frame>
      ![maxlength validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_maxlength.png)
    </Frame>

    <Card title="maxLength" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength">
      Refer to MDN documentation for more details about the maxlength attribute.
    </Card>
  </Accordion>

  <Accordion title="required">
    This validator checks whether a value exists in the input field.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validatorss.png)
    </Frame>

    It is recommended to use this validator with other validators like [minlength](#minlength-validator) to check if there is no value at all.

    <Frame>
      ![required validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validators.png)
    </Frame>

    <Card title="required" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required">
      Refer to MDN documentation for more details about the required attribute.
    </Card>
  </Accordion>

  <Accordion title="email">
    This validator checks whether the input value is a valid email. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#required-validator) validator.

    <Frame>
      ![email validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_email.png#center)
    </Frame>

    <Card title="email" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email">
      Refer to MDN documentation for more details about email input validation.
    </Card>
  </Accordion>

  <Accordion title="pattern validator">
    This validator checks whether the input value matches the specified pattern (for example, a [regex expression](https://www.regexbuddy.com/regex.html)).

    <Warning>
      **Important:** Pattern validators can only be applied to input fields of type **"text"** or **"string"**. They cannot be used with input fields of type **"number"**. If you need to validate numeric input with specific patterns (such as preventing leading zeros), you must either:

      * Use a text input field instead of a number input field, or
      * Create a custom validator that handles the numeric validation logic
    </Warning>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_pattern.png#center)
    </Frame>

    <Card title="pattern validator" icon="link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern">
      Refer to MDN documentation for more details about the pattern attribute.
    </Card>
  </Accordion>

  <Accordion title="custom expression validator">
    This validator allows you to validate a form element based on computed expressions that can reference other values from the process data store, not just the current form element being validated.

    <Frame>
      ![custom expression validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_expression.png)
    </Frame>

    Example used:

    ```javascript Simple comparison theme={"system"}
    return ${user.endDate} > ${user.startDate}
    ```

    The validator uses a code editor where you can write computed expressions that must eventually return `true` (valid) or `false` (invalid). The expression can contain process data store values and will be evaluated dynamically.

    <Info>
      The `customExpression` validator runs only when the field value is not empty or missing, similar to other predefined validators.
    </Info>

    **Key features:**

    * **Dynamic validation**: Based on other process values, not just the current field
    * **Computed expressions**: Write JavaScript expressions that return boolean values
    * **Real-time updates**: Re-evaluates when referenced process data changes
    * **Universal compatibility**: Available for all form elements

    **Expression examples:**

    <CodeGroup>
      ```javascript Simple comparison theme={"system"}
      return ${app.endDate} > ${app.startDate}
      ```

      ```javascript Complex validation theme={"system"}
      return ${app.userAge} >= 18 && ${app.hasParentConsent} === true
      ```

      ```javascript Numeric validation theme={"system"}
      return ${app.totalAmount} <= ${app.availableBalance}
      ```
    </CodeGroup>

    <Warning>
      **Important considerations:**

      * The expression **must** return a boolean value (`true` for valid, `false` for invalid)
      * Use proper syntax when referencing process data store values with `${}`
      * Ensure referenced process data keys exist to avoid runtime errors
      * The validator is asynchronous and will be re-evaluated when dependent data changes
    </Warning>
  </Accordion>
</AccordionGroup>

Other predefined validators are also available:

<AccordionGroup>
  <Accordion title="isSameOrBeforeToday">
    This validator can be used to validate [datepicker](./ui-component-types/form-elements/datepicker-form-field) inputs. It checks whether the selected date is today or in the past. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#required-validator) validator.

    <Frame>
      ![isSameOrBeforeToday](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_issameday.png)
    </Frame>
  </Accordion>

  <Accordion title="isSameOrAfterToday">
    This validator can be used to validate datepicker inputs. It checks whether the selected date is today or in the future. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#required-validator) validator.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_issamedayafter.png)
    </Frame>
  </Accordion>
</AccordionGroup>

## Validator compatibility with input field types

Different validators work with different input field types. Here's a compatibility matrix:

| Validator           | Text Fields | Number Fields | Email Fields | Date Fields |
| ------------------- | ----------- | ------------- | ------------ | ----------- |
| required            | ✅           | ✅             | ✅            | ✅           |
| min                 | ❌           | ✅             | ❌            | ❌           |
| max                 | ❌           | ✅             | ❌            | ❌           |
| minLength           | ✅           | ❌             | ✅            | ❌           |
| maxLength           | ✅           | ❌             | ✅            | ❌           |
| email               | ❌           | ❌             | ✅            | ❌           |
| pattern             | ✅           | ❌             | ✅            | ❌           |
| customExpression    | ✅           | ✅             | ✅            | ✅           |
| isSameOrBeforeToday | ❌           | ❌             | ❌            | ✅           |
| isSameOrAfterToday  | ❌           | ❌             | ❌            | ✅           |

<Info>
  To ensure the validation of all form elements within a card upon executing a Save Data action such as "Submit" or "Continue," follow these steps:

  * When adding an event handler to a button inside a card, locate the dropdown menu labeled **Add form to validate**.
  * From the dropdown menu, select the specific form or individual form elements that you wish to validate.
  * By choosing the appropriate form or elements from this dropdown, you can ensure comprehensive validation of your form.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_validators.png)
  </Frame>
</Info>

***

## Common expression patterns

The `customExpression` validator supports JavaScript expressions that return `true` (valid) or `false` (invalid). Below are patterns for common validation scenarios.

### Date comparison

Validate that one date comes after another:

```javascript theme={"system"}
return new Date(${application.endDate}) > new Date(${application.startDate})
```

### Required-if (conditional required)

Make a field required only when another field has a specific value:

```javascript theme={"system"}
if (${application.hasSpouse} === true) {
  return ${application.spouseName} !== null && ${application.spouseName} !== ""
}
return true
```

### Regex patterns

Validate a string against a pattern using `match()`:

<CodeGroup>
  ```javascript UK National Insurance Number (NINO) theme={"system"}
  return /^[A-CEGHJ-PR-TW-Z]{1}[A-CEGHJ-NPR-TW-Z]{1}[0-9]{6}[A-D]{1}$/.test(${application.nino})
  ```

  ```javascript Phone number (10 digits) theme={"system"}
  return /^\d{10}$/.test(${application.phoneNumber})
  ```

  ```javascript Postal code (UK format) theme={"system"}
  return /^[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2}$/.test(${application.postalCode})
  ```
</CodeGroup>

<Tip>
  For simple pattern matching on text fields, the [pattern validator](#pattern-validator) may be more appropriate. Use `customExpression` when you need to combine patterns with other logic.
</Tip>

### Null and empty checks

Handle optional fields that should be validated only when populated:

```javascript theme={"system"}
if (${application.alternateEmail} === null || ${application.alternateEmail} === "") {
  return true
}
return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(${application.alternateEmail})
```

### Cross-field validation

Compare multiple field values:

```javascript theme={"system"}
return ${application.confirmPassword} === ${application.password}
```

<Info>
  **Hidden fields skip validation.** When a form element is hidden via a hide condition, all its validators (including `customExpression`) are disabled. Hidden fields do not block form submission. If you need to validate data regardless of field visibility, use a [business rule action](../../actions/business-rule-action/business-rule-action) on the backend.

  For full details on how visibility affects validation, see [Event Handlers — Form validation](./event-handlers#form-validation).
</Info>

***

## Custom validators

Additionally, custom validators can be created within the web application and referenced by name. These custom validators can have various configurations such as execution type, name, parameters, and error message.

1. **Execution type** - synchronous/asynchronous validator
2. **Name** - name provided by the developer to uniquely identify the validator
3. **Params** - if the validator needs inputs to decide if the field is valid or not, you can pass them using this list
4. **Error Message** - the message that will be displayed if the field is not valid

<Warning>
  The error that the validator returns **MUST** match the validator name.
</Warning>

<Frame>
  ![custom validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_custom.png#center)
</Frame>

### Custom validator example

Below you can find an example of a custom validator (`currentOrLastYear`) that restricts date selection to the current or the previous year:

#### currentOrLastYear

```typescript theme={"system"}
currentOrLastYear: function currentOrLastYear(AC: AbstractControl): { [key: string]: any } {
    if (!AC) {
      return null;
    }

    const yearDate = moment(AC.value, YEAR_FORMAT, true);
    const currentDateYear = moment(new Date()).startOf('year');
    const lastYear = moment(new Date()).subtract(1, 'year').startOf('year');

    if (!yearDate.isSame(currentDateYear) && !yearDate.isSame(lastYear)) {
      return { currentOrLastYear: true };
    }

    return null;
```

#### smallerOrEqualsToNumber

Below is another custom validator example that validates form input asynchronously. The validator is called `smallerOrEqualsToNumber` and takes an array of `params` as an input.

<Info>
  For this custom validator the execution type should be marked as `async` using the UI Designer.
</Info>

```typescript theme={"system"}
export function smallerOrEqualsToNumber (params$: Observable<any>[]): AsyncValidatorFn {
  return (AC): Promise<ValidationErrors | null> | Observable<ValidationErrors | null> => {
    return new Observable((observer) => {
      combineLatest(params$).subscribe(([maximumLoanAmount]) => {
        const validationError =
          maximumLoanAmount === undefined || !AC.value || Number(AC.value) <= maximumLoanAmount ? null : {smallerOrEqualsToNumber: true};

        observer.next(validationError);
        observer.complete();
      });
    });
  };
}
```

If the input value is undefined or the input value is smaller or equal to the maximum loan amount value, the function returns `null`, indicating that the input is valid. If the input value is greater than the maximum loan amount value, the function returns a validation error object with a key `smallerOrEqualsToNumber` and a value of true, indicating that the input is invalid.

<Info>
  For more details about custom validators please check the [SDK documentation](../../../sdks/).
</Info>

<Tip>
  Using validators in your application can help ensure that the data entered by users is valid, accurate, and consistent, improving the overall quality of your application.
</Tip>

It can also help prevent errors and bugs that may arise due to invalid data, saving time and effort in debugging and fixing issues.

***

## Academy courses

<CardGroup>
  <Card title="Hide and Disable course" icon="graduation-cap" href="https://academy.flowx.ai/explore/hide-and-disable-ui-elements">
    Academy course on building dynamic UI logic with hide and disable conditions, including validation behavior
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**Academy\_HideAndDisable**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/698d604b-904f-4cb9-8d70-68a492b8216d/config/40430d0b-3f16-4146-9231-26cc68e35ccb/processes) project for working validation and hide/disable examples.
</Tip>


# UI Flows
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-flows

Build reusable, multi-platform user interfaces that work across web, iOS, and Android without the overhead of BPMN processes.

## Overview

UI Flows are a project resource for use cases where full BPMN mapping is unnecessary. Full BPMN mapping for simple UI experiences introduces overhead and complexity. UI Flows also eliminate subprocesses that add layers to the main process for UI purposes only.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows1.png)
</Frame>

UI Flows support web (Angular/React), iOS, and Android. They separate UI definitions from process logic, providing an alternative to BPMN processes when business orchestration is not required.

<CardGroup>
  <Card title="Multi-Platform Support" icon="mobile">
    Create UI once and deploy to web, iOS, and Android with platform-specific configurations
  </Card>

  <Card title="Process Integration" icon="link">
    Launch FlowX processes from UI Flows when needed using the Start Process action
  </Card>

  <Card title="Navigation Management" icon="map">
    Manage Navigation Areas, pages, and scrolling within UI Flows Designer
  </Card>

  <Card title="Task Manager Integration" icon="list-check">
    Embed Task Manager as a UI component to display task lists
  </Card>

  <Card title="AI Chat Integration" icon="comments">
    Add Chat components for conversational AI experiences powered by AI agents
  </Card>
</CardGroup>

### Key characteristics

| Characteristic            | Description                                                                                         |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| **Project Resource**      | Managed as independent project resources, separate from process definitions                         |
| **UI Designer**           | Configure using UI Designer (navigation areas appear as UI assets instead of BPMN nodes)            |
| **Navigation Areas**      | Add navigation areas as UI assets to define the user journey                                        |
| **Components**            | Supports components, substitution tags, media items, and enumerations                               |
| **Theme Support**         | Themes apply to UI Flows                                                                            |
| **Data Model**            | UI Flows have their own data model for localization and formatting                                  |
| **FLX UI Flow Component** | The `flx-ui-flow` component renders UI Flows and can be embedded in any container app               |
| **Custom Components**     | Custom components can be added to UI Flows                                                          |
| **Experience Type**       | UI Flows can be **Flow-Based** (default) or **Chat-Based** (connected to a conversational workflow) |

<Warning>
  **Platform selection is permanent**: When creating a UI Flow, you select a platform (web or mobile). This cannot be changed later. Changing the project-level platform setting does not update existing UI Flow resources.
</Warning>

***

## Experience types

UI Flows support two experience types, selected when creating the UI Flow:

<CardGroup>
  <Card title="Flow-Based" icon="window">
    **Default.** Traditional UI flows with navigation areas, forms, and standard components. Use for structured user journeys.
  </Card>

  <Card title="Chat-Based" icon="comments">
    Optimized for conversational experiences. Connected to a [conversational workflow](/5.9/ai-platform/conversational-workflows) that powers all Chat components in the UI Flow.
  </Card>
</CardGroup>

### Chat-Based UI Flows

When you select **Chat-Based** as the experience type:

* You must select an **AI Conversational Workflow** to connect to the UI Flow
* All Chat components in the UI Flow use this workflow by default
* The workflow can be changed later in the UI Flow **Settings** page (gear icon in the sidenav)

### UI Flow Settings

Chat-Based UI Flows have a **Settings** page accessible from the gear icon in the UI Flow editor sidenav. The Settings page includes:

| Tab              | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| **Variables**    | Manage UI Flow variables (available for all UI Flows)                |
| **Chat Options** | Select or change the conversational workflow for Chat-Based UI Flows |

<Note>
  The **Chat Options** tab is only enabled for Chat-Based UI Flows. Flow-Based UI Flows only show the Variables tab.
</Note>

### Expiry time

UI Flow general settings include an **Expiry time** field that sets how long a UI Flow session stays valid. The field accepts either an **ISO 8601 duration** (for example `PT3M22S` for 3 minutes 22 seconds) or a **cron expression** (for example `0 0 9-17 * * MON-FRI`) for time-based expiry.

***

## When to use UI Flows

### Use UI Flows for

Use UI Flows when you need a user interface without BPMN process orchestration:

<CardGroup>
  <Card title="Information Display" icon="table-columns">
    Dashboards, reports, and static content that doesn't require process orchestration
  </Card>

  <Card title="Task Management" icon="list-check">
    Task lists and task management interfaces with embedded Task Manager component
  </Card>

  <Card title="Navigation Shells" icon="compass">
    App navigation structures, home pages, and menu systems
  </Card>

  <Card title="Form Collections" icon="file-lines">
    Data entry forms that start processes but don't need their own process context
  </Card>
</CardGroup>

### Use processes for

Use processes when you need:

<CardGroup>
  <Card title="Business Logic" icon="sitemap">
    Complex workflows with business rules, approvals, and integrations
  </Card>

  <Card title="State Management" icon="floppy-disk">
    Applications requiring process state tracking and persistence
  </Card>

  <Card title="Orchestration" icon="gears">
    Multi-step operations with decision points and parallel execution
  </Card>
</CardGroup>

### Combine both approaches

<Tip>
  Use UI Flows as the main app shell and **Start Process actions** to launch business processes when needed.
</Tip>

**Example:**

* UI Flow provides the home screen, navigation, and dashboard
* User clicks "Apply for Loan" → the Start Process action launches the loan process
* After process completion, user returns to the UI Flow dashboard

***

## How navigation works

A UI Flow behaves like a single-page app: one UI Flow session hosts a set of routable views, and moving between them updates the browser URL without leaving the session.

* **Root navigation areas are the routes.** Each root-level navigation area — a **Page**, root **Zone**, or root **Tab Bar** — is a routable view with its own URL. **Modals** are routed too, addressed through a `modalId` query parameter on top of the current view. This page also refers to routable views as *screens* or *root views* — they are the same thing.
* **One session, one data store.** All views in a UI Flow share the same session and its [session variables](#session-variables). Navigating between views never resets the session — data fetched on one view is available on every other view.
* **Navigate To actions define the navigation graph.** The [route map](#route-map-and-breadcrumbs) — shortest paths, breadcrumbs, and back navigation — is computed automatically from the Navigate To actions you configure.
* **URLs are real.** Views support query parameters, [deep linking](#deep-linking), browser back/forward, and refresh recovery through the [navigation stack](#navigation-stack).

Inside a single view, a Page or Zone additionally has a **layout mode**: **Single page** renders all child areas on one screen, while **Wizard** shows them one at a time with Next/Back navigation. Layout mode controls rendering *within* a view; it is separate from routing *between* views.

***

## Key features

<Info>
  **What you can build with UI Flows:**

  * Create and render UI Flows for Web, iOS, and Android platforms
  * Navigate between Navigation Areas with the Navigate To action
  * Fetch and display data with the Start Workflow action
  * Start FlowX processes via the Start Process action, or embed one with the Process Renderer component
  * Embed the Task Manager and Chat components
  * Configure the UI Flow data model for localization
</Info>

### Navigation Areas management

In UI Flows Designer:

* Create pages and navigation flows
* Configure navigation areas (Page, Tabbar, Zone, Modal)
* Set up header and footer zones (web only)
* Define home pages with navigation icons

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows4.png)
</Frame>

### Start Process action

Launch FlowX processes from UI Flows:

* Start processes on button clicks or events
* Pass data from UI Flow to process
* Return to UI Flow after process completion

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_process_ui.png)
</Frame>

### Navigate To action

Configure navigation within UI Flows:

* Navigate to specific Navigation Areas
* Scroll to Container elements
* Create multi-step wizards

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows2.png)
</Frame>

### Task Manager component

Embed Task Manager in UI Flows:

* Display task lists
* Filter and search tasks
* Launch tasks in context

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows3.png)
</Frame>

### Home page support

* Designate any page as the home page
* Automatic home icon in navigation
* Return to home from any screen

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows5.png)
</Frame>

### Global components

Add persistent components that appear across all screens in a UI Flow:

* **Breadcrumbs** (web only) — show navigation path and enable click-to-navigate
* **Chat** (web + mobile) — embed AI-powered conversational interface

### Process Renderer component

Embed a full FlowX process inside a UI Flow screen (web only):

* Start any process from the current app
* Pass data from the UI Flow data store to the process
* Maintain consistent navigation with URL-based process tracking

### Export and import

You can export and import UI Flows to transfer them between projects or environments.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows6.png)
</Frame>

#### Exporting

1. Open the context menu on the UI Flows list page
2. Select **Export** for the UI Flow you want to export
3. The UI Flow is downloaded as a ZIP file

#### Importing

1. Open the context menu on the UI Flows list page and select **Import**
2. Select the ZIP file exported from another project or environment
3. If UI Flows with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
4. Choose a strategy for each conflicting UI Flow (or use **Apply to all**):
   * **Keep both** - imports the UI Flow as a new copy alongside the existing one
   * **Replace** - overwrites the existing UI Flow with the imported version
   * **Skip this one** - keeps the existing UI Flow unchanged
5. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

***

## Creating a UI Flow

<Steps>
  <Step title="Create UI Flow resource">
    In FlowX Designer, navigate to your project and create a new UI Flow as a project resource.

    * Navigate to **UI Flows** tab
    * Click **+ Add** button
    * Enter a name and description
    * Select platform (Web or Mobile)
    * Select experience type: **Flow-Based** (default) or **Chat-Based**
    * If Chat-Based, select the **AI Conversational Workflow** to connect

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows7.png)
    </Frame>
  </Step>

  <Step title="Design navigation structure">
    Open UI Flows Designer and manage Navigation Areas:

    * Add Navigation Areas (pages)
    * Configure navigation type (Single Page or Wizard)
    * Setup zones (header, content, footer) for web
    * Define navigation flow between areas
  </Step>

  <Step title="Add UI components">
    Build your interface using the component library:

    * Drag and drop UI components
    * Configure component properties
    * Add Task Manager component if needed
    * Setup data bindings
  </Step>

  <Step title="Configure event handlers">
    Setup interactivity and navigation:

    * **Start Process**: Launch processes when needed
    * **Navigate To**: Move between Nav areas or scroll to containers
    * **External**: Open a link in a new tab
  </Step>

  <Step title="Set home page (optional)">
    Designate a page as the home page:

    * Select the Navigation Area
    * Mark as "Home Page"
    * Configure home icon appearance
  </Step>

  <Step title="Test and validate">
    Test your UI Flow:

    * Preview across platforms
    * Test navigation flow
    * Verify Start Process actions work
    * Check Task Manager integration
  </Step>
</Steps>

***

## Configuring the Start Process action

The Start Process action allows you to launch FlowX processes from UI Flows. Although UI Flows do not require a process and user tasks, they support actions for process initiation.

<Frame>
  ![Start Process action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_ui_process_action.png)
</Frame>

### How it works

When a process is started from a UI Flow:

1. The `FlxProcessRenderer` component is **dynamically added**, replacing the UI Flow content
2. The process renderer inherits configuration from the UI Flow and shares common stores:
   * API URL and static assets path
   * Workspace and project IDs
   * Language and locale settings
   * Build information
   * Theme and fonts
   * Substitution tags and media items

<Info>
  When configuring the `FlxUIFlow` component in your container app, ensure the `processApiPath` parameter is set to enable process starting capabilities.
</Info>

### Configuration steps

<Steps>
  <Step title="Add button or trigger">
    Add a UI component that will trigger the process (typically a Button).
  </Step>

  <Step title="Add an event handler">
    Configure the handler:

    * In the **Event Handlers** section, add a handler
    * Select **Start Process** as the action type
    * Choose the process definition to start from the dropdown
  </Step>

  <Step title="Configure forms and data">
    The Start Process action allows you to configure:

    * **Process selection**: Select the process to start
    * **Forms to submit**: Choose which forms to include with the start request
    * **Custom body**: Define which data to send as start parameters

    ```json theme={"system"}
    {
      "customerId": "${uiData.customer.id}",
      "applicationAmount": "${uiData.amount}"
    }
    ```
  </Step>

  <Step title="Configure behavior">
    Set what happens after process starts:

    * Navigate to process UI
    * Stay in UI Flow
    * Show confirmation message
  </Step>

  <Step title="Optional: Add analytics">
    Configure analytics tracking:

    * **Analytics name**: Set a name for tracking
    * **Custom payload**: Add additional data for analytics
  </Step>
</Steps>

***

## Configuring the Start Workflow action

<Frame>
  ![Start Workflow action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_ui_wf_action.png)
</Frame>

The Start Workflow action allows you to execute integration workflows directly from UI Flows. Unlike Start Process, which creates a full process instance with state management, Start Workflow executes lighter-weight integration workflows that return results immediately.

<Frame>
  ![UI Flow Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ui_flow_designer.png)
</Frame>

### When to use Start Workflow vs Start Process

| Use Case               | Action Type    | Description                                              |
| ---------------------- | -------------- | -------------------------------------------------------- |
| **Data fetching**      | Start Workflow | Retrieve data from APIs or databases                     |
| **Simple operations**  | Start Workflow | Execute stateless operations (calculations, validations) |
| **Integrations**       | Start Workflow | Call external services and return results                |
| **Business processes** | Start Process  | Multi-step processes requiring state management          |
| **User journeys**      | Start Process  | Processes with multiple user interactions                |

### How it works

When a workflow is started from a UI Flow:

1. The workflow is executed via the Runtime Manager API
2. Input parameters are mapped from UI Flow data
3. The API returns a `workflowInstanceUuid` for tracking
4. UI Flow subscribes to SSE events for workflow completion
5. Results are mapped back to UI Flow data for display

### API endpoint

```
POST /rtm/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start-workflow
```

| Parameter              | Type | Description                             |
| ---------------------- | ---- | --------------------------------------- |
| `workspaceId`          | Path | Workspace identifier                    |
| `appId`                | Path | Application identifier                  |
| `resourceDefinitionId` | Path | Resource definition ID for the workflow |
| Request body           | JSON | Workflow input parameters               |

**Response:**

```json theme={"system"}
{
  "workflowInstanceUuid": "uuid-string",
  "status": "started|pending|failed"
}
```

### SSE events

The UI Flow subscribes to Server-Sent Events (SSE) to receive workflow completion notifications.

**Event type:** `UI_FLOW_WORKFLOW_RESPONSE`

```json theme={"system"}
{
  "eventType": "UI_FLOW_WORKFLOW_RESPONSE",
  "workflowInstanceUuid": "uuid-string",
  "status": "completed|failed|timeout",
  "data": {},
  "timestamp": "ISO-8601"
}
```

### Configuration steps

<Steps>
  <Step title="Add a UI component">
    Add a component that will trigger the workflow — typically a **Button**, or use an **On Load** event on a Page to fetch data automatically when the screen opens.
  </Step>

  <Step title="Add an event handler">
    Configure the handler:

    * In the **Event Handlers** section, add a handler
    * Select **Start Workflow** as the action type
    * Choose the integration workflow to execute from the **Workflow** dropdown
  </Step>

  <Step title="Configure start parameters (optional)">
    If the workflow needs input data, check **Add start params** and provide a JSON body. Use `${}` expressions to pass current session data:

    ```json theme={"system"}
    {
      "customerId": "${customerId}",
      "requestType": "balance_inquiry"
    }
    ```
  </Step>

  <Step title="Configure UX options">
    | Option                    | Description                                                            |
    | ------------------------- | ---------------------------------------------------------------------- |
    | **Show loader**           | Display a loading indicator while the workflow executes                |
    | **Dismiss on completion** | Automatically close the modal when the workflow finishes (modals only) |

    <Note>
      **Dismiss on completion** is a user-initiated dismiss: the user clicks the button with Start Workflow, the workflow runs, and the modal closes when the workflow finishes. The close is downstream of the user's action, so this pattern is compliant with the [modal lifecycle rule](../process/design-principles#modals-are-dismissed-only-by-user-interaction).
    </Note>
  </Step>
</Steps>

### How workflow output reaches your components

Unlike processes, there is no `responseKey` configuration for Start Workflow actions. When a workflow completes, its output is **automatically merged** into the UI Flow's session variables. Any component on any page in the same session can reference the returned data immediately.

<Steps>
  <Step title="Workflow returns output">
    The workflow's **End** node determines what data is returned. The output parameters configured on the workflow definition control the shape of the response.

    <Warning>
      The workflow must return a **named object**, not a raw array. For example, return `{"submissions": [...]}` instead of `[...]`. The auto-merge expects an object with keys — returning a bare array will cause an error.
    </Warning>
  </Step>

  <Step title="Output auto-merges into session variables">
    When the workflow completes, its output is delivered via a real-time SSE event and deep-merged into the session's data store. Existing session variables are preserved — new keys are added and matching keys are updated.

    <Info>
      Arrays in the output **replace** existing arrays with the same key (they are not appended). If you need to combine results from multiple workflow calls, handle the merge in the workflow itself.
    </Info>
  </Step>

  <Step title="Components reactively update">
    Any component bound to the returned keys updates automatically. For example, if the workflow returns `{"foundSubmissions": [...]}`, a table with its source bound to `${foundSubmissions}` displays the data as soon as the workflow completes.
  </Step>
</Steps>

<Tip>
  Use the **Variables** tab in the UI Flow session console to inspect what data is currently available. This is the fastest way to verify whether the workflow output arrived and what keys it contains.
</Tip>

### Example: Fetch and display a list

1. Create a workflow called `getSubmissions` that queries a database and returns output as a named object:
   ```json theme={"system"}
   {
     "foundSubmissions": [
       { "_id": "69c66a...", "submissionDetails": { "lineOfBusiness": "Property", ... } },
       { "_id": "69cb7c...", "submissionDetails": { "lineOfBusiness": "Casualty", ... } }
     ]
   }
   ```
2. On your Page, add a **Table** component and bind its data source to `${foundSubmissions}`.
3. Add a **Start Workflow** action (triggered **On Load** or via a Button click) pointing to `getSubmissions`.
4. When the page loads (or the button is clicked), the workflow runs and the table populates automatically.

<Info>
  Start Workflow supports organization-aware execution with organization ID propagation from the workflow instance for proper multi-tenant isolation.
</Info>

### Page parameters vs session variables

These are two separate concepts:

| Concept               | Purpose                                                                                                 | How data gets there                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Page parameters**   | Define URL query parameters for deep linking and navigation between pages                               | Configured via the **Parameters** gear icon on a Page or Modal            |
| **Session variables** | Store workflow output, file upload responses, and start params — shared across all pages in the session | Populated **automatically** when workflows complete or files are uploaded |

Page parameters appear in the browser URL (e.g., `?userId=123`) and are passed via **Navigate To** actions. Session variables live in the session's data store and are the primary mechanism for getting workflow output into UI components.

<Info>
  In processes, a `responseKey` wraps the action output under a specific key in the process data model. UI Flows do not use `responseKey` — the workflow output object is merged directly into session variables. Make sure your workflow End node returns data with descriptive top-level keys (e.g., `foundSubmissions`, `accountDetails`) to avoid collisions with other session data.
</Info>

***

## Configuring the Navigate To action

The Navigate To action handles navigation within UI Flows and scrolling to specific elements.

### Navigation behavior: Route vs Scroll

The Navigate To action either **routes** (changes the URL/view) or **scrolls** (anchor navigation) depending on the destination and the area's [layout mode](#how-navigation-works) (single page vs wizard):

| Scenario                                                     | Behavior   | Example                                                        |
| ------------------------------------------------------------ | ---------- | -------------------------------------------------------------- |
| Destination inside same Navigation Area (single page)        | **Scroll** | Button in Card X scrolls to Card Y within the same Page        |
| Destination inside same Navigation Area (wizard navigation)  | **Route**  | Button navigates to next step in a wizard Page                 |
| Destination outside Navigation Area, different root          | **Route**  | Button in Page 1 navigates to Page 2                           |
| Destination outside Navigation Area, same root (wizard)      | **Route**  | Button in Zone 1 routes to Zone 2 within a wizard Page         |
| Destination outside Navigation Area, same root (single page) | **Scroll** | Button in Zone 1 scrolls to Zone 2 within a single-page layout |
| Destination is a Modal                                       | **Route**  | Button opens Modal as a routed view                            |

<Accordion title="Detailed navigation examples">
  **Example layout:**

  ```
  Page 1 - Single page form
  ├── Zone - Header
  │   └── Card 1 (Button 2)
  ├── Zone - Content
  │   ├── Card 2 (Button 1)
  │   ├── Modal
  │   │   └── Card 8
  │   ├── Card 9 (Button 3)
  │   └── Card 10 (Button 4)
  └── Zone - Footer
      └── Card 3

  Page 2 - Wizard navigation
  ├── Card 4
  ├── Card 5
  └── Card 6
  ```

  **Action outcomes:**

  | Action   | Destination     | Result                      |
  | -------- | --------------- | --------------------------- |
  | Button 1 | Modal/Card 8    | **Route** to modal          |
  | Button 2 | Card 10         | **Scroll** to Card 10       |
  | Button 3 | Card 4 (Page 2) | **Route** to Page 2, Card 4 |
</Accordion>

<Info>
  Under the hood, every Navigate To updates the URL and pushes a browser history entry, then scrolls the destination element into view. **Route** vs **Scroll** in the table describes the visible outcome: whether the rendered view changes, or the current view scrolls to an anchor.
</Info>

### Configuring the action

<Steps>
  <Step title="Add navigation trigger">
    Add a Button or menu item that triggers navigation.
  </Step>

  <Step title="Select the destination">
    * Add an event handler → **Navigate To**
    * Pick the destination from the **Destination** dropdown

    Available destinations include all Navigation Areas in the hierarchy plus their first-level children (Card, Container, Custom). Selecting a child element scrolls to it when it is on the currently visible view, or navigates to its view and then scrolls to it.
  </Step>

  <Step title="Optional: Pass parameters">
    If the destination root view defines [route parameters](#configuring-route-parameters), use the **Destination Parameters Mapping** field to pass values.
  </Step>
</Steps>

<Note>
  Scrolling is automatic — there is no separate scroll configuration on the action. The renderer smooth-scrolls the destination element into view after navigating.
</Note>

***

## Embedding Task Manager

Add Task Manager as a UI component in UI Flows to display task lists without requiring a process.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows_tm.png)
</Frame>

<Steps>
  <Step title="Add Task Manager component">
    In UI Flows Designer, add the Task Manager component to a Container or Card.
  </Step>

  <Step title="Select a view">
    Configure which view to display in the Task Manager:

    * Select the view you want from your available views list
    * Each view can have different columns, filters, and sorting options
  </Step>
</Steps>

***

## Embedding Chat component

The Chat component enables interactive conversations with AI agents directly within UI Flows. It provides a conversational interface for AI-powered workflows, supporting real-time message exchange, session persistence, and memory capabilities.

<CardGroup>
  <Card title="AI Agent Conversations" icon="robot">
    Connect to conversational workflows powered by AI agents
  </Card>

  <Card title="Session Persistence" icon="id-badge">
    Automatic session handling across page refreshes
  </Card>
</CardGroup>

<Steps>
  <Step title="Add Chat component">
    In UI Flows Designer, select **Chat** from the UI Assets panel and drag it onto the canvas.
  </Step>

  <Step title="Configure the agent workflow">
    In the Settings tab, specify the **Agent ID / Workflow Name** for the conversational workflow.

    <Warning>
      Only **conversational workflows** can be integrated with the Chat component. Task-oriented workflows cannot be used.
    </Warning>
  </Step>

  <Step title="Customize appearance">
    Use the Styles tab to configure header, messages, and input styling. Theme Admin provides comprehensive theming options.
  </Step>
</Steps>

<Card title="Chat Component Documentation" icon="comments" href="/5.9/ai-platform/chat-component">
  View the complete Chat component documentation for detailed configuration, memory capabilities, SDK integration, and best practices.
</Card>

***

## Process Renderer component

The Process Renderer component allows you to embed a full FlowX process directly inside a UI Flow screen. This enables hybrid apps that combine UI Flow navigation with traditional process-based screens. Available on **web only**.

### Configuration

<Steps>
  <Step title="Add the component">
    In the UI Flows Designer, drag **Process Renderer** from the **Complex Components** category in the UI Assets panel onto a **Page** or **Modal**.

    <Warning>
      A container can have either a Process Renderer or other children, but not both. If the target container already has child components, the Process Renderer cannot be added.
    </Warning>
  </Step>

  <Step title="Select a process">
    In the **Settings** panel under **Properties**, use the **Process** dropdown to select the process to embed. The dropdown lists all processes in the current app.
  </Step>

  <Step title="Configure start parameters (optional)">
    Use the **Start Params** field to pass data from the UI Flow to the process. Enter a JSON object, optionally using `${keyName}` expressions to reference values from the UI Flow data store.

    ```json theme={"system"}
    { "name": ${app.name}, "loanAmount": ${app.loanAmount} }
    ```
  </Step>
</Steps>

### Properties

| Property         | Type              | Required | Description                                                                                                 |
| ---------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| **Process**      | Dropdown          | Yes      | The process to embed (selected by resource definition ID)                                                   |
| **Start Params** | JSON / expression | No       | Data passed to the process on start. Supports `${keyName}` expressions resolved from the UI Flow data store |

### Style

| Property    | Options                  | Default |
| ----------- | ------------------------ | ------- |
| **Width**   | Fill, Fixed              | `Fill`  |
| **Height**  | Auto, Fixed              | `Auto`  |
| **Margins** | Top, Right, Bottom, Left | —       |

### Placement rules

* Can only be placed as a direct child of a **Page** or **Modal**
* A container with a Process Renderer cannot have other child components (mutual exclusivity)
* **Web only** — not available on iOS or Android

### Navigation behavior

When a process is started inside the Process Renderer, a `processUuid` parameter is added to the URL and mapped to the current view.

| Navigation method                   | Behavior                                                           |
| ----------------------------------- | ------------------------------------------------------------------ |
| **Browser back / Breadcrumb click** | Restores the previously started process instance from the view map |
| **Navigate To action**              | Restarts the process and resets the view entry                     |
| **Modal context**                   | Skips URL parameter matching (process runs independently)          |

***

## Global components

Global components persist across all screens in a UI Flow. They are rendered outside the normal navigation tree and remain visible as users navigate between screens. Currently two global component types are available: **Breadcrumbs** (web only) and **Chat** (web and mobile).

### Adding global components

In the UI Flows Designer, the left panel navigator shows a split view:

* **Navigation tree** (top) — the normal component hierarchy
* **Global Components** (bottom) — persistent components that appear across screens

To add a global component:

1. Click the **+** button in the Global Components section
2. Select **Breadcrumbs** or **Chat** from the dropdown
3. Only one instance of each type is allowed per UI Flow

<Frame>
  ![Adding a global component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/adding_breadcrumbs.png)
</Frame>

When a new screen (Page, root Zone, or root Tab Bar) is added to the UI Flow, all existing global components are automatically **assigned** to it. To control which screens a global component appears on, right-click the component in the Global Components section and use **Apply To** to check or uncheck specific screens. Unassigned components appear grayed out in the navigator for that screen and are not rendered at runtime.

***

### Breadcrumbs

Breadcrumbs display the user's current navigation path within a UI Flow and provide click-to-navigate functionality. They are automatically generated from the navigation hierarchy.

| Feature               | Description                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| **Auto-generated**    | Built from the navigation stack as users move between screens             |
| **Click to navigate** | Click any breadcrumb item to navigate directly to that screen             |
| **Dynamic updates**   | Update automatically as users navigate deeper into the UI Flow            |
| **Back navigation**   | Support browser back button and breadcrumb click navigation               |
| **Deep link support** | Breadcrumbs are correctly generated when accessing a screen via deep link |

#### Configuration properties

| Property              | Description                                                                                                                             | Default |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Collapse Mode**     | Controls how breadcrumbs collapse when the path is long. `NONE` shows all items; `MIDDLE` collapses intermediate items into an ellipsis | `NONE`  |
| **Max Visible Items** | Maximum number of breadcrumb items to display when collapse mode is `MIDDLE` (minimum 2)                                                | `4`     |
| **Show Home Icon**    | Display a home icon as the first breadcrumb item                                                                                        | `true`  |

#### Setting breadcrumb titles

Breadcrumb labels are populated from the **Title** property on root navigation areas. To configure:

1. Select a **Page**, root **Zone**, or root **Tab Bar** in the navigator
2. Open **Settings** → **Properties**
3. Set the **Title** field

Titles support dynamic values:

* **Substitution tags** — use `@@tag_name` syntax
* **Data store values** — use `${keyName}` syntax to reference values from the UI Flow data store

#### Navigation behavior

Breadcrumbs maintain a route hierarchy that avoids circular paths. For example, if a user navigates A → B → A, the breadcrumb trail resets to just A rather than showing a loop.

#### Theming

Breadcrumbs support theming through the Theme Admin with two theme elements:

* **Breadcrumbs** (container) — padding, gap
* **Breadcrumb Item** — border radius, padding, gap, with state modifiers for default, active, hover, and active hover (text style, text color, background color, border color, icon color)

Two system icons are used:

* `sys_BreadcrumbsHome` — the home icon
* `sys_BreadcrumbsSeparator` — the separator between items

<Frame>
  ![Breadcrumbs theming](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/breadcrumbs_theming.png)
</Frame>

#### Accessibility

| Element              | HTML Tag | Attributes                                                            |
| -------------------- | -------- | --------------------------------------------------------------------- |
| Breadcrumb container | `nav`    | `aria-label` (localized via `@@sys_a11y_breadcrumb` substitution tag) |
| Breadcrumb list      | `ol`     | —                                                                     |
| Breadcrumb item      | `li`     | `aria-current="page"` on the active (last) item                       |
| Separator            | `img`    | `aria-hidden`                                                         |

***

### Chat as a global component

The Chat component can be added as a global component with three display modes:

* **Fill** — renders inline within a container
* **Floating** — renders as a floating action button (FAB)
* **Fullscreen** — renders as a fullscreen overlay

Floating and Fullscreen modes can be combined so the FAB expands to fullscreen on click.

To change the display mode, right-click the Chat component in the Global Components section and select **Edit Display Types**. Use **Apply To** to assign or unassign the Chat component from specific screens.

<Card title="Chat Component Documentation" icon="comments" href="/5.9/ai-platform/chat-component">
  View the complete Chat component documentation for detailed configuration and best practices.
</Card>

## Route management

Route management gives you control over URL structure, query parameters, and navigation paths within UI Flows. Define parameters on root views, pass data between screens via query strings, and let breadcrumbs auto-generate from the navigation graph.

<Info>
  URL-based route management (query parameters, `modalId`, deep linking, the session-storage navigation stack) applies to the **web** renderer. Mobile renderers manage navigation natively with their own navigation stack.
</Info>

### Route types

| Route Type                 | Description                                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| **UI Flow Route**          | The base route defined by the UI Flow where the FLX UI Flow component is added                    |
| **Process Instance Route** | When a process is started, an additional route segment is added based on the process instance UID |
| **Deep Link Route**        | Direct URL access to specific screens using route parameters and query strings                    |

### Configuring route parameters

Root views (Pages, Modals) can define query parameters that control what data is available when that view loads.

<Steps>
  <Step title="Select a root view">
    In the UI Flows Designer, select a **Page** or **Modal** in the navigation tree.
  </Step>

  <Step title="Open the parameters config">
    In the config panel, click the **Parameters** gear icon to open the parameters modal.
  </Step>

  <Step title="Add parameters">
    Define parameters with the following properties:

    | Property          | Description                                                       |
    | ----------------- | ----------------------------------------------------------------- |
    | **Name**          | The query parameter key (must be unique within the view)          |
    | **Default Value** | Value used if the parameter is not provided at navigation time    |
    | **Required**      | Whether the parameter must be passed when navigating to this view |

    The modal shows a URL path preview so you can see how the parameters will appear in the browser URL.
  </Step>
</Steps>

<Frame>
  ![Edit Parameters modal showing route parameters with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
</Frame>

### Passing parameters with Navigate To

When configuring a **Navigate To** action that targets a root view with parameters, a **Destination Parameters** field appears. Enter a JSON mapping that resolves parameter values from the UI Flow data store:

```json theme={"system"}
{
  "userId": "${user.id}",
  "status": "${userData.status}"
}
```

When the destination view changes, the Designer auto-populates required parameters as a template so you know which values to provide.

### Route map and breadcrumbs

The route map is a navigation graph computed automatically from all **Navigate To** actions in the UI Flow. It determines:

* **Shortest paths** from the root view to any other view
* **Breadcrumb labels** generated from view titles
* **Back navigation** — clicking a breadcrumb navigates to that view with the correct query parameters preserved

When navigating, the system:

1. Evaluates the parameter mapping JSON against the UI Flow data store
2. Adds destination parameters to the URL
3. Removes parameters that belong only to the source view
4. Preserves parameters shared between source and destination

### Modal navigation

Modals integrate with route management through a `modalId` query parameter:

* Opening a modal adds `modalId={flowxUuid}` to the URL
* Closing a modal removes the `modalId` parameter
* On page reload, the `modalId` in the URL automatically re-opens the correct modal
* Modals on the same root open locally without triggering root navigation

### Navigation stack

UI Flows maintain a navigation stack that tracks the user's path through screens. The stack is persisted in the browser's **session storage**, enabling:

* **Browser back button support** — Users can navigate back through their history
* **Refresh recovery** — The stack survives page refreshes; it is cleared when the browser tab is closed
* **Programmatic navigation** — Use the `NAVIGATE_TO` action type to navigate to specific screens
* **Circular path prevention** — Navigating A → B → A resets the breadcrumb trail to just A

<Note>
  The stack is stored under a single session-storage key per browser tab. If two container apps hosting different UI Flows run on the same origin in the same tab, they overwrite each other's navigation history.
</Note>

### Deep linking

Deep linking allows direct URL access to specific UI Flow screens. URLs are updated as users navigate, enabling:

* Sharing links to specific screens
* Bookmarking specific states
* Browser history navigation with meaningful URLs

### On Load event integration

When a Navigate To action targets a screen, the destination screen's [On Load event](./ui-designer/event-handlers#triggers) re-fires automatically. This ensures data initialization workflows run each time a user navigates to that screen, even if the screen was previously loaded in the session. Back/forward and breadcrumb navigation do **not** re-fire On Load — only an explicit Navigate To resets it.

The same behavior applies to [intent-based navigation](/5.9/ai-platform/conversational-workflows#navigate-in-ui-flow-node) triggered by AI chat agents — the destination screen's On Load event re-fires to initialize data for the new navigation context.

***

## Start parameters

Start parameters allow you to pass initial data when launching a UI Flow. Configure them in the Designer and provide values at runtime via the API request body or query strings in SaaS container apps.

### How start parameters work

Start parameters are an arbitrary JSON object passed when starting a UI Flow session. They are:

* Persisted on the `ui_flow_session` record in the database
* Returned in both start and status API responses
* Available to renderers throughout the session lifecycle

### Passing start parameters

<Tabs>
  <Tab title="Designer (testing)">
    When running a UI Flow from the Designer, a **Start params JSON** code editor appears in the Run dialog. Enter valid JSON to pass as start parameters:

    ```json theme={"system"}
    {
      "clientId": "123",
      "tier": "premium"
    }
    ```

    The Run button is disabled until the JSON is valid. Default value is `{}`.

    <Frame>
      ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
    </Frame>
  </Tab>

  <Tab title="SaaS container app">
    In a SaaS container app, start parameters are extracted from URL query strings. Reserved parameters (`projectId`, `workspaceId`, `processUuid`, `uiFlowSessionUuid`, `chatSessionId`, `language`, `locale`) are used for configuration; all other query parameters are passed as start parameters.

    The `language` and `locale` query parameters are preserved across SDK navigation and page refreshes, so you don't need to manage them manually via session storage.

    For example, this URL:

    ```
    https://app.example.com/?projectId=xyz&clientId=123&tier=premium
    ```

    passes `{"clientId": "123", "tier": "premium"}` as start parameters.

    Configuration parameters are automatically scrubbed from the browser URL after initialization.
  </Tab>

  <Tab title="API">
    Pass start parameters in the request body when calling the start UI Flow endpoint:

    ```
    POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flows/{uiFlowName}
    ```

    ```json theme={"system"}
    {
      "clientId": "123",
      "tier": "premium"
    }
    ```

    The `startParams` field is optional and defaults to an empty object.
  </Tab>
</Tabs>

***

## Session variables

Session variables persist data across all pages that share the same UI Flow session ID. They allow you to pass data between workflows, file uploads, and UI components within a single session without relying on process state.

### Variable sources

Variables are automatically collected from the following sources and merged into the session:

| Source                   | Description                                                                                              | Merge behavior                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Start parameters**     | JSON provided when starting the UI Flow session                                                          | Initial values, set once                                          |
| **Workflow output**      | Output from Start Workflow actions — must be a named object (e.g., `{"items": [...]}`, not a bare array) | Deep-merged with existing variables                               |
| **File upload response** | Document Plugin response from Upload actions                                                             | Stored under the **Response Key** configured on the Upload action |

<Info>
  Process output (from Process Renderer components) is handled separately and is not part of session variables.
</Info>

### Using variables in components

Reference session variables in component configurations using `${}` syntax:

```text theme={"system"}
${clientId}
${uploadedDocument.fileId}
${workflowResult.status}
```

### Variables tab

The UI Flow session console in the Designer includes a **Variables** tab that displays all current session variables. This is useful for debugging and verifying that data flows correctly between workflows, file uploads, and UI components.

<Frame>
  ![Variables tab in the UI Flow session console showing session variables](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
</Frame>

The session console tabs are:

| Tab           | Description                                  |
| ------------- | -------------------------------------------- |
| **Variables** | Current session variable values (read-only)  |
| **Processes** | Process instances launched from the session  |
| **Workflows** | Workflow instances launched from the session |
| **Audit Log** | Session activity log                         |

<Info>
  Session variables are **read-only** in the console — you cannot edit them directly. Variables are updated automatically when workflows complete or files are uploaded.
</Info>

***

## Platform considerations

<Tabs>
  <Tab title="Web">
    **Full Feature Support:**

    * All UI component types available
    * Navigation Areas with zones (header, content, footer)
    * Full wizard and single-page navigation
    * Task Manager component integration

    **Excluded Navigation Areas:**

    * Stepper & Step

    **Available Root Navigation Areas:**

    * Page
    * Tabbar
    * Zone

    **Component Hierarchy:**

    ```
    Page (multiple allowed)
    ├── Card
    ├── Container
    ├── Custom
    ├── Modal
    ├── Zone
    └── Tabbar

    Tabbar
    └── Tab (multiple allowed)
        ├── Card
        ├── Container
        ├── Custom
        ├── Modal
        ├── Zone
        └── Tabbar

    Modal (multiple allowed)
    ├── Card
    ├── Container
    └── Custom
    ```
  </Tab>

  <Tab title="Mobile">
    **Mobile-Optimized (iOS & Android):**

    * Preview selection via dropdown (iOS/Android)
    * Basic Navigation Areas (Page, Tab Bar), no header/footer zones
    * Platform-specific property overrides (copy to/from iOS/Android)

    **Excluded Navigation Areas:**

    * Zone
    * Stepper & Step

    **Excluded Components:**

    * Task management
    * Table

    **Available Root Navigation Areas:**

    * Page
    * Tabbar (only as first root - not enforced in UI Designer)

    **Component Hierarchy:**

    ```
    Page (multiple allowed)
    ├── Card
    ├── Container
    ├── Custom
    └── Modal

    Tabbar
    └── Tab (multiple allowed)
        ├── Card
        ├── Container
        ├── Custom
        └── Modal

    Modal (multiple allowed)
    ├── Card
    ├── Container
    └── Custom
    ```
  </Tab>
</Tabs>

<Tip>
  Use the platform selection subheader in UI Designer to switch between platforms and configure platform-specific behaviors.
</Tip>

***

## Best practices

### Architecture

<CardGroup>
  <Card title="Use UI Flows for UI Logic" icon="layer-group">
    Keep navigation, layout, and presentation in UI Flows
  </Card>

  <Card title="Use Processes for Business Logic" icon="diagram-project">
    Delegate complex business operations to processes via Start Process action
  </Card>

  <Card title="Minimize Data in UI Flows" icon="minimize">
    Session variables last only for the session lifetime — pass data that must be durably persisted to processes
  </Card>

  <Card title="Reuse Across Projects" icon="recycle">
    Design UI Flows for reuse across multiple apps
  </Card>
</CardGroup>

### Design

**DO:**

✅ Create clear navigation hierarchies\
✅ Use descriptive names for Navigation Areas\
✅ Test on all target platforms before deployment\
✅ [Configure accessibility properties](../platform-deep-dive/accessibility) for mobile
✅ Use Task Manager component for task-centric applications

**DON'T:**

❌ Duplicate business logic in UI Flows and Processes\
❌ Create overly complex navigation structures\
❌ Ignore platform-specific limitations\
❌ Skip [accessibility configuration](../platform-deep-dive/accessibility) for mobile apps
❌ Use UI Flows when you need process state management

***

## Migration from subprocess-based navigation

If you currently use subprocesses for UI-only scenarios, consider migrating to UI Flows:

<Steps>
  <Step title="Identify UI-only subprocesses">
    Review your subprocesses and identify those that:

    * Only display UI without business logic
    * Act as navigation shells
    * Could be replaced with simpler UI
  </Step>

  <Step title="Create equivalent UI Flow">
    Build a UI Flow that replicates the UI functionality:

    * Create Navigation Areas matching subprocess pages
    * Add UI components
    * Setup navigation using Navigate To actions
  </Step>

  <Step title="Migrate process launches">
    Replace subprocess starts with Start Process actions:

    * Keep actual business processes as processes
    * Launch them from UI Flows when needed
  </Step>

  <Step title="Test thoroughly">
    Verify functionality across platforms:

    * Navigation works correctly
    * Process launches function properly
    * Data flows as expected
  </Step>

  <Step title="Deprecate old subprocesses">
    Once validated, remove the unnecessary subprocess layers.
  </Step>
</Steps>

***

## UI Flow permissions

UI Flow permissions sit on top of the [runtime authorization model](../../setup-guides/access-management/roles-permissions-matrix). Each UI Flow has a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API.

### Default role on creation

When a UI Flow is created, a default runtime role is assigned automatically so the UI Flow is reachable from day one. The default is the project-level **User** role; change it from the UI Flow Permissions page.

### Configuring permissions

Open **Settings → Permissions** in the UI Flow editor. The Permissions page lets you:

* Select one or more runtime roles allowed to start the UI Flow
* Remove the default role and replace it with a project-version-scoped role
* View the resulting permission set for each role

Role changes are saved as part of the UI Flow resource and travel with project export/import.

### Runtime enforcement

When a user starts a UI Flow:

1. The runtime checks the user's roles against the UI Flow's allowed roles list.
2. If the user has none of the allowed roles, the request is rejected and a permission toast is shown in the Designer-hosted runtime preview. In the deployed app, the UI Flow is not listed and the start endpoint returns 403.
3. Input parameters are validated against the UI Flow's input schema before the session is created.

Within a UI Flow session, individual components can be hidden or disabled via permission-based hide/disable rules. These evaluate at runtime against the user's permission set, the same way they evaluate JavaScript expressions today. See [Hide condition / Disabled condition](#hide-condition--disabled-condition).

### Migration from earlier versions

UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.

***

## Caching

UI Flow definitions are cached at runtime to speed up rendering — the flow definition, its name, allowed roles, templates, and custom-component data. The cache is populated lazily on first use and is invalidated automatically when a UI Flow's resources are overridden at runtime.

### Clearing the cache manually

If you need to force a refresh, use the **Clear cache** action in the UI Flow editor:

<Steps>
  <Step title="Open the UI Flow">
    Open the UI Flow whose cache you want to clear.
  </Step>

  <Step title="Clear cache">
    Open the **⋮** (more) menu in the page header and select **Clear cache**. This clears the cached definition for that UI Flow.
  </Step>
</Steps>

<Note>
  **Clear cache** requires delete permission on the UI Flow. It clears the cache for the selected UI Flow only.
</Note>

***

## Limitations and compatibility

### Current limitations

<Warning>
  UI Flows have the following limitations:
</Warning>

* **Data Persistence**: Session variables persist only for the lifetime of the session — data that must outlive the session must be passed to processes for storage
* **Complex Conditionals**: For complex business rules, use processes instead
* **Reusable UI**: Reusable UI components are not yet supported in UI Flows
* **Undo-Redo**: Limited undo-redo support in UI Flows Designer
* **Multi-Instance (Concurrent)**: While a UI Flow can launch multiple process instances (for example, separate buttons for mortgage or credit card applications), it cannot yet have multiple instances running concurrently from the same page

### Future enhancements

Planned for future releases:

* **Reusable UI integration**: Integrate reusable UI components in UI Flows with input/output parameters and data mappers
* **Enhanced resource management**: Undo-redo, resource usages, merge conflicts, and audit logging
* **Advanced actions**: Start project with entrypoint, start process/project with mappings
* **Additional UI components**: Modal as UI element
* **AI integration**: Additional AI-powered features for UI Flows

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Start Process action not working">
    **Possible causes:**

    * Process definition not published
    * Missing required process parameters
    * Insufficient permissions

    **Solutions:**

    * Ensure process definition is published in target environment
    * Verify all required parameters are mapped in the action
    * Check user has permission to start the process
    * Review browser console for error messages
  </Accordion>

  <Accordion title="Navigate To action not working">
    **Possible causes:**

    * Target destination no longer exists (deleted or moved in the navigation tree)
    * Destination not available on the current platform
    * Navigation configuration error

    **Solutions:**

    * Verify the destination still exists in the navigation tree and reselect it in the handler
    * Review navigation configuration in UI Designer
    * Test navigation flow step by step
  </Accordion>

  <Accordion title="Task Manager component not showing tasks">
    **Possible causes:**

    * Task Manager not properly configured
    * User doesn't have tasks
    * Filter configuration too restrictive

    **Solutions:**

    * Verify Task Manager component configuration
    * Check user has assigned tasks in Task Manager
    * Review and adjust filter settings
    * Ensure Task Manager service is running
  </Accordion>

  <Accordion title="Platform-specific configuration not applying">
    **Possible causes:**

    * Wrong platform selected in preview
    * Configuration not saved
    * Cache issues

    **Solutions:**

    * Switch platform tabs and verify configuration
    * Save UI Flow and refresh browser
    * Clear browser cache and reload
    * Test on actual device if possible
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="UI Designer Overview" href="./ui-designer/ui-designer" icon="paintbrush">
    Learn about UI Designer capabilities and interface
  </Card>

  <Card title="Navigation Areas" href="../process/navigation-areas" icon="map">
    Understand navigation area types as used in BPMN processes
  </Card>

  <Card title="Event Handlers" href="./ui-designer/event-handlers" icon="bolt">
    Configure event handlers including Start Process and Navigate To
  </Card>

  <Card title="Task Management" href="../platform-deep-dive/core-extensions/task-management/task-management-overview" icon="list-check">
    Learn about Task Manager and task management capabilities
  </Card>

  <Card title="Chat Component" href="/5.9/ai-platform/chat-component" icon="comments">
    Add conversational AI experiences to your UI Flows
  </Card>

  <Card title="AI Platform" href="/5.9/ai-platform/ai-in-flowx" icon="microchip">
    Explore AI capabilities in FlowX
  </Card>
</CardGroup>


# Accessibility
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/accessibility

WCAG 2.1 Level AA accessibility support in FlowX.AI, including screen reader compatibility, keyboard navigation, and configurable accessibility properties across web and mobile platforms.

## Overview

FlowX.AI provides **WCAG 2.1 Level AA** accessibility compliance for applications built with the platform. Accessibility features are configured in the **UI Designer** and automatically applied by the renderers at runtime across web (Angular, React), iOS, and Android platforms.

<CardGroup>
  <Card title="Screen readers" icon="ear-listen">
    ARIA labels, hints, roles, and live regions automatically mapped to UI components
  </Card>

  <Card title="Keyboard navigation" icon="keyboard">
    Full keyboard support with visible focus indicators and logical tab order
  </Card>

  <Card title="Cross-platform" icon="mobile">
    Web, iOS (VoiceOver), and Android (TalkBack) support from a single configuration
  </Card>
</CardGroup>

***

## Configuring accessibility in UI Designer

Accessibility properties are configured in the **Settings** tab of the component configuration panel. Properties are saved in `platformDisplayOptions.flowxProps.accessibility` for the generic platform and apply across all renderers.

```json theme={"system"}
{
  "platformsDisplayOptions": [
    {
      "flowxProps": {
        "accessibility": {
          "label": "",
          "decorative": false,
          "altText": "",
          "role": ""
        }
      },
      "platform": "generic"
    }
  ]
}
```

### Available properties

| Property       | Description                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **label**      | Accessibility label announced by screen readers. Use when the component has no visible label or needs a different label for assistive technologies.                 |
| **decorative** | Marks the element as decorative so it is ignored by assistive technologies.                                                                                         |
| **altText**    | Short descriptive text alternative for images, announced by screen readers.                                                                                         |
| **role**       | Landmark role for navigation areas. Options: `main`, `navigation`, `search`, `form`, `header`, `footer`, `aside`, `region`, `dialogue`, `alertdialogue`, `section`. |

***

## Accessibility properties by component

Not all components expose the same accessibility properties. The SDK automatically reads certain existing properties (like label and placeholder text) and exposes them to assistive technologies. Additional properties can be configured where needed.

### Form elements

| Component            | Auto-read by SDK                        | Configurable in Designer |
| -------------------- | --------------------------------------- | ------------------------ |
| **Input**            | label, text, placeholder, helper, error | accessibility label      |
| **Single select**    | label, text, placeholder, helper, error | accessibility label      |
| **Multi select**     | label, text, placeholder, helper, error | accessibility label      |
| **Date picker**      | label, text, placeholder, helper, error | accessibility label      |
| **Text area**        | label, text, placeholder, helper, error | accessibility label      |
| **Slider**           | label, value, helper, error             | accessibility label      |
| **Checkbox**         | label, text, helper, error              | accessibility label      |
| **Radio button**     | label, text, helper, error              | accessibility label      |
| **Switch**           | label, text, helper, error              | accessibility label      |
| **Segmented button** | label, text, helper, error              | accessibility label      |

<Tip>
  Use the accessibility label when the component has no visible label or text, or when you need a different label for assistive technologies.
</Tip>

### Interactive elements

| Component       | Auto-read by SDK | Configurable in Designer        |
| --------------- | ---------------- | ------------------------------- |
| **Button**      | label            | accessibility label (icon-only) |
| **File upload** | label            | accessibility label (icon-only) |

<Tip>
  For icon-only buttons, always set an accessibility label so screen readers can announce the button's purpose.
</Tip>

### Display elements

| Component        | Auto-read by SDK | Configurable in Designer |
| ---------------- | ---------------- | ------------------------ |
| **Text**         | text             | decorative               |
| **Link**         | text             | decorative               |
| **Image**        | —                | alt text, decorative     |
| **Message**      | text             | decorative               |
| **Card**         | title, subtitle  | —                        |
| **Form**         | title            | —                        |
| **File preview** | title, subtitle  | —                        |

### Navigation areas

| Component | Auto-read by SDK | Configurable in Designer |
| --------- | ---------------- | ------------------------ |
| **Step**  | title            | accessibility label      |
| **Tab**   | title            | accessibility label      |
| **Modal** | title            | accessibility label      |

<Tip>
  Use the accessibility label for navigation areas when the area has no visible label or text, or when a different label is needed for assistive technologies.
</Tip>

***

## Landmark roles

Navigation areas are assigned landmark roles that help screen reader users understand the page structure and navigate between regions.

### Default roles

| Navigation area | Default role | Configurable |
| --------------- | ------------ | ------------ |
| **Page**        | `main`       | No           |
| **Stepper**     | `navigation` | No           |
| **Step**        | `navigation` | No           |
| **Tabbar**      | `navigation` | No           |
| **Tab**         | `navigation` | No           |
| **Modal**       | `dialogue`   | No           |
| **Zone**        | `section`    | Yes          |

### Zone roles

Zones can be configured with a landmark role to convey their purpose to assistive technologies:

* `main` — primary content area
* `section` — generic section (default)
* `nav` — navigation region
* `header` — page or section header
* `footer` — page or section footer
* `aside` — complementary content

***

## Keyboard navigation

FlowX.AI applications support full keyboard navigation with visible focus indicators. Focus is indicated by an outline around the active element.

### General patterns

| Key               | Action                                                                 |
| ----------------- | ---------------------------------------------------------------------- |
| `Tab`             | Move focus to the next interactive element                             |
| `Shift + Tab`     | Move focus to the previous interactive element                         |
| `Enter` / `Space` | Activate the focused element (button, link, toggle)                    |
| `Escape`          | Close modal or dismiss popup                                           |
| Arrow keys        | Navigate within a component (radio options, slider, select list, tabs) |

### Component-specific behavior

<AccordionGroup>
  <Accordion title="Button / File upload" icon="hand-pointer">
    * `Tab` focuses the element (skipped if disabled)
    * `Space` / `Enter` executes the action
  </Accordion>

  <Accordion title="Input / Text area" icon="input-text">
    * `Tab` focuses the element and enables typing (skipped if disabled)
    * Arrow keys move within the text
    * If the element has a clear button, `Tab` navigates to it; `Space` / `Enter` clears the value
  </Accordion>

  <Accordion title="Checkbox" icon="square-check">
    * `Tab` focuses the first option, then subsequent options
    * `Space` / `Enter` selects or deselects the focused option
    * After the last option, `Tab` moves to the next element
  </Accordion>

  <Accordion title="Radio / Segmented button" icon="circle-dot">
    * `Tab` focuses the selected option (or the first option if none selected)
    * `Down` / `Right` arrow moves focus forward and selects
    * `Up` / `Left` arrow moves focus backward and selects
    * Navigation wraps cyclically through options
  </Accordion>

  <Accordion title="Switch" icon="toggle-on">
    * `Tab` focuses the element (skipped if disabled)
    * `Space` / `Enter` toggles the value
  </Accordion>

  <Accordion title="Slider" icon="sliders">
    * `Tab` focuses the slider knob
    * `Up` / `Right` arrow increases by one step
    * `Down` / `Left` arrow decreases by one step
  </Accordion>

  <Accordion title="Select" icon="list-dropdown">
    * `Tab` focuses the element and enables typing (skipped if disabled)
    * `Up` / `Down` arrow opens the listbox
    * In the listbox: arrows navigate options, `Enter` selects and closes, `Escape` closes
    * Focus remains on the input while the listbox is open
    * If the element has a clear button, `Tab` navigates to it
  </Accordion>

  <Accordion title="Multi select" icon="list-check">
    * `Tab` focuses the element and enables typing (skipped if disabled)
    * In the listbox: arrows navigate options, `Enter` selects (without closing), `Escape` closes
    * Focus remains on the input while the listbox is open
  </Accordion>

  <Accordion title="Tabs" icon="folder">
    * `Tab` moves focus to the active tab header
    * `Left` / `Right` arrow navigates between tab headers cyclically
    * `Space` / `Enter` activates the focused tab
    * `Tab` from the active tab header moves focus to the first focusable element in the tab content
  </Accordion>

  <Accordion title="Modal" icon="window-maximize">
    * When opened, focus moves to the first focusable element inside the modal
    * Focus is trapped within the modal — `Tab` cycles through modal content
    * `Escape` closes the modal
  </Accordion>

  <Accordion title="Accordion" icon="bars-staggered">
    * `Tab` focuses the accordion trigger
    * `Enter` / `Space` expands or collapses the section
    * When expanded, `Tab` moves to the first focusable element in the content
    * When collapsed, `Tab` moves to the next accordion header cyclically
  </Accordion>
</AccordionGroup>

***

## Screen reader support

FlowX.AI renderers automatically apply ARIA attributes to components based on their type and configuration. Many attributes are auto-bound — no manual configuration needed.

### Auto-bound ARIA attributes

<AccordionGroup>
  <Accordion title="Form elements" icon="input-text">
    | Attribute                                         | Applied to                        |
    | ------------------------------------------------- | --------------------------------- |
    | `aria-describedby`                                | Helper text, error messages       |
    | `aria-required`                                   | Required fields                   |
    | `aria-invalid`                                    | Fields with validation errors     |
    | `aria-checked`                                    | Checkbox, radio, switch state     |
    | `aria-selected`                                   | Select option state               |
    | `aria-expanded`                                   | Select/multiselect dropdown state |
    | `aria-autocomplete`                               | Select search input               |
    | `aria-valuemin`, `aria-valuemax`, `aria-valuenow` | Slider                            |
  </Accordion>

  <Accordion title="Navigation and containers" icon="compass">
    | Attribute                                      | Applied to                       |
    | ---------------------------------------------- | -------------------------------- |
    | `role="tablist"`                               | Tab container, stepper           |
    | `role="tab"`, `aria-controls`, `aria-selected` | Individual tabs                  |
    | `role="tabpanel"`, `aria-describedby`          | Tab content panels               |
    | `role="dialog"`, `aria-modal`                  | Modals                           |
    | `aria-labelledby`                              | Modal (references title)         |
    | `aria-current`                                 | Active step in stepper           |
    | `aria-expanded`                                | Accordion headers                |
    | `role="radiogroup"`                            | Radio/segmented button container |
  </Accordion>

  <Accordion title="Interactive elements" icon="hand-pointer">
    | Attribute                       | Applied to                       |
    | ------------------------------- | -------------------------------- |
    | `aria-label`                    | Buttons, links (from label/text) |
    | `aria-disabled`                 | Disabled buttons and inputs      |
    | `aria-pressed`                  | Toggle buttons                   |
    | `role="button"` / `role="link"` | Buttons and links                |
    | `aria-live="polite"`            | Message components               |
  </Accordion>

  <Accordion title="Display elements" icon="image">
    | Attribute            | Applied to                               |
    | -------------------- | ---------------------------------------- |
    | `alt`                | Images (from alt text property)          |
    | `aria-hidden="true"` | Decorative images, text, links, messages |
  </Accordion>
</AccordionGroup>

***

## Platform support

### Implementation status

| Feature                       | Web (Angular/React) | iOS (VoiceOver) | Android (TalkBack) |
| ----------------------------- | :-----------------: | :-------------: | :----------------: |
| Accessibility labels          |          ✅          |        ✅        |          ✅         |
| Decorative elements           |          ✅          |        ✅        |          ✅         |
| Image alt text                |          ✅          |        ✅        |          ✅         |
| Landmark roles                |          ✅          |        —        |          —         |
| Keyboard navigation           |          ✅          |       N/A       |         N/A        |
| ARIA auto-binding             |          ✅          |       N/A       |         N/A        |
| Form elements (screen reader) |          ✅          |        ✅        |          ✅         |
| Date picker (screen reader)   |          🚧         |        🚧       |         🚧         |
| Single select (screen reader) |          🚧         |        🚧       |         🚧         |
| Multi select (screen reader)  |          🚧         |        🚧       |         🚧         |

<Info>
  🚧 indicates components with partial screen reader support that is actively being improved.
</Info>

### Version availability

| Platform                | Accessibility feature                     | Available since |
| ----------------------- | ----------------------------------------- | --------------- |
| **Web** (Angular/React) | WCAG 2.1 Level AA compliance              | FlowX.AI 5.1.1  |
| **Android**             | Accessibility properties from UI Designer | FlowX.AI 5.1.2  |
| **iOS**                 | VoiceOver support                         | FlowX.AI 5.1.3  |

***

## Client responsibilities

FlowX.AI handles accessibility for platform-rendered components automatically. However, some accessibility aspects depend on the container application and content authored by the client.

### What FlowX.AI handles

* ARIA attributes on all rendered components
* Keyboard navigation and focus management
* Screen reader announcements for form states (errors, required fields)
* Focus trapping in modals
* Landmark roles for navigation areas

### What clients are responsible for

<AccordionGroup>
  <Accordion title="HTML and page structure" icon="code">
    * Set the `lang` attribute on the `html` element for correct screen reader pronunciation
    * Provide a unique `title` for each page
    * Ensure viewport zoom is not disabled (`user-scalable=yes`)
    * Use logical heading hierarchy (`h1` → `h2` → `h3`, no skipping levels)
  </Accordion>

  <Accordion title="Content authoring" icon="pen">
    * Write descriptive button and link labels (avoid "click here", "read more")
    * Provide meaningful alt text for images
    * Mark decorative elements appropriately
    * Use plain language ([8th grade reading level](https://datayze.com/readability-analyzer.php))
    * Use left-aligned text for LTR languages, right-aligned for RTL
  </Accordion>

  <Accordion title="Color and contrast" icon="palette">
    * Normal text: minimum **4.5:1** contrast ratio
    * Large text: minimum **3:1** contrast ratio
    * Icons and UI elements: minimum **3:1** contrast ratio
    * Do not use color as the only way to convey information
    * Ensure error, warning, and success states are distinguishable without color
  </Accordion>

  <Accordion title="Media and animation" icon="film">
    * Avoid autoplaying media
    * Provide captions for video content
    * Avoid strobing or flashing animations (seizure triggers)
    * Respect `prefers-reduced-motion` for custom animations
  </Accordion>

  <Accordion title="Mobile considerations" icon="mobile">
    * Support both portrait and landscape orientation
    * Ensure touch targets are large enough for easy activation
    * Provide sufficient space between interactive elements for scrolling
    * Avoid horizontal scrolling
  </Accordion>
</AccordionGroup>

***

## Testing recommendations

<CardGroup>
  <Card title="Keyboard testing" icon="keyboard">
    Navigate your application using only the keyboard. Verify that all interactive elements are reachable via `Tab`, that focus is visible, and that focus order matches the visual layout.
  </Card>

  <Card title="Screen reader testing" icon="ear-listen">
    Test with VoiceOver (macOS/iOS), TalkBack (Android), or NVDA/JAWS (Windows). Verify labels are announced correctly and form states are communicated.
  </Card>

  <Card title="Automated testing" icon="robot">
    Use axe-core or similar tools in your CI pipeline to catch common accessibility issues. Storybook's `addon-a11y` plugin provides real-time feedback during development.
  </Card>

  <Card title="High contrast modes" icon="circle-half-stroke">
    Activate Windows High Contrast mode or inverted colors. Verify content is still legible and interactive elements are distinguishable.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Platform considerations" icon="desktop" href="../building-blocks/ui-designer/platform-considerations">
    Platform-specific configuration for web, iOS, and Android renderers
  </Card>

  <Card title="UI Designer" icon="pen-ruler" href="../building-blocks/ui-designer/ui-designer">
    Overview of the UI Designer and component configuration
  </Card>

  <Card title="Localization and i18n" icon="language" href="../building-blocks/ui-designer/localization-and-i18n">
    Language, region, and formatting configuration
  </Card>

  <Card title="WCAG 2.1 Guidelines" icon="scale-balanced" href="https://www.w3.org/WAI/WCAG21/quickref/">
    Official W3C quick reference for WCAG 2.1 success criteria
  </Card>
</CardGroup>


# FlowX.AI Advancing Controller
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-components/advancing-controller

The Advancing Controller is a support service for the FlowX.AI Engine that enhances the efficiency of advancing operations. It facilitates equal distribution and redistribution of the workload during scale-up and scale-down scenarios.

The Advancing Controller microservice monitors process advancement in both PostgreSQL and Oracle Database configurations, ensuring efficient workload distribution across worker instances.

## Usage

The Advancing Controller service is responsible for managing and optimizing the advancement process in the PostgreSQL or Oracle databases. It ensures efficient workload distribution, performs cleanup tasks, and monitors the status of worker pods.

If a worker pod fails, the service reassigns its work to other pods to prevent [**process instances**](../../projects/runtime/active-process/process-instance) from getting stuck.

<Check>
  It is essential to have the Advancing Controller service running alongside the FlowX Engine for uninterrupted instance advancement.
</Check>

<Tip>
  Ensure that both the FlowX Engine and the Advancing Controller microservices are up and running concurrently for optimal performance.
</Tip>

## Configuration

For detailed instructions on how to set up the Advancing Controller microservice, refer to the following guide:

<Card title="Advancing controller setup guide" href="../../../setup-guides/advancing-controller-setup-guide" />


# FlowX.AI Events Gateway
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-components/events-gateway

The FlowX Events Gateway is a service that centralizes the communication with Server-Sent Events (SSE) messages from Backend to Frontend.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/events_gateway_archi.png)
</Frame>

The FlowX Events Gateway serves as a central component for handling and distributing events within the system:

<CardGroup>
  <Card title="Event processing" icon="gears" href="#event-processing" />

  <Card title="Message distribution" icon="stack-exchange" href="#stack-exchange" />

  <Card title="Event publication" icon="tower-broadcast" href="#tower-broadcast" />

  <Card title="Integration with Redis" icon="network-wired" href="#network-wired" />
</CardGroup>

### Event processing

The Events Gateway system is responsible for receiving and processing events from various sources, such as the [**FlowX Engine**](./flowx-engine) and [**Task Management**](../core-extensions/task-management/task-management-overview). It acts as an intermediary between these systems and the rest of the system components.

<Tip>
  It is a reusable component and is also used in administration scenarios to provide feedback without a refresh—for example, surfacing misconfigurations so an error can be displayed in real-time during configuration.
</Tip>

### Message distribution

The Events Gateway system reads messages from the Kafka topic (`messaging_events_topic`) and distributes them to relevant components within the system. It ensures that the messages are appropriately routed to the intended recipients for further processing.

### Event publication

The Events Gateway system plays a crucial role in publishing events to the frontend renderer (FE renderer). It communicates with the frontend renderer using `HTTP` via `WebFlux`. By publishing events, it enables real-time updates and notifications on the user interface, keeping the user informed about the progress and changes in the system.

It is designed to efficiently send updates to the frontend in the following scenarios:

* When reaching a specific [**User Task (UT)**](../../building-blocks/node/user-task-node), a notification is sent to ensure the corresponding screen is rendered promptly.
* When specific actions require data to be sent to the user interface from a node.

### Integration with Redis

<Info>
  [**Redis**](../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis) plays an important role within the platform. It handles every message and is mandatory for the platform to function correctly, especially with the frontend. The platform relies on Redis to ensure that the messages are distributed efficiently and that the correct instance with the SSE connection pointer for the recipient is always reached.
</Info>

The events-gateway system also interacts with Redis to publish events on a stream. This allows other components in the system to consume the events from the Redis stream and take appropriate actions based on the received events.

In these situations, the FlowX Engine places a message on Kafka for the Events Gateway. The Events Gateway then retrieves the message and stores it in Redis.

In summary, the events-gateway system acts as a hub for event processing, message distribution, and event publication within the system. It ensures efficient communication and coordination between various system components, facilitating real-time updates and maintaining system consistency.

For more details about how to configure events-gateway microservice, check the following section:

<Card title="Events gateway configuration" href="../../../setup-guides/events-gateway-setup" />


# FlowX.AI Engine
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-components/flowx-engine

Core service that runs process definitions, generates UI, and communicates with the frontend, custom integrations, and plugins.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Engine%20Diagram%20%281%29.png)
</Frame>

<Info>
  The Web renderer supports both Angular and React. The diagram above uses Angular as an example, but the same architecture applies to React-based deployments.
</Info>

## Orchestration

Creating and interacting with process instances is pretty straightforward, as most of the interaction happens automatically and is handled by the engine.

The only points that need user interaction are starting the process and executing user tasks on it (for example when a user fills in a form on the screen and saves the results).

<Card title="FlowX Engine setup guide" href="../../../setup-guides/flowx-engine-setup-guide/" icon="files" />


# FlowX.AI Audit
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/audit

The Audit service provides a centralized location for all audit events. The following details are available for each event.

* **Timestamp** - the date and time the event occurred, the timestamp is displayed in a reversed chronologically order
* **User** - the entity who initiated the event, could be a username or a system
* **Subject** - the area or component of the system affected by the event

<AccordionGroup>
  <Accordion title="Possible values">
    <ul>
      <li>Process Instance</li>
      <li>Process variables</li>
      <li>Token</li>
      <li>Task</li>
      <li>Exception</li>
      <li>Process definition</li>
      <li>Node</li>
      <li>Action</li>
      <li>UI Component</li>
      <li>General Settings</li>
      <li>Swimlane</li>
      <li>Swimlane Permissions</li>
      <li>Connector</li>
      <li>Enumeration</li>
      <li>Enumeration Value</li>
      <li>Substitution Tag</li>
      <li>Content Model</li>
      <li>Language</li>
      <li>Source System</li>
      <li>Image</li>
      <li>Font file</li>
      <li>Custom Component</li>
      <li>Reusable UI Template</li>
      <li>Reusable Business Rule</li>
      <li>UI Flow</li>
    </ul>
  </Accordion>
</AccordionGroup>

* **Event** - the specific action that occurred

<AccordionGroup>
  <Accordion title="Possible values">
    <ul>
      <li>Create</li>
      <li>Update</li>
      <li>Update bulk</li>
      <li>Update state</li>
      <li>Edit</li>
      <li>Export</li>
      <li>Import</li>
      <li>Delete</li>
      <li>Clone</li>
      <li>Start</li>
      <li>Start with inherit</li>
      <li>Advance</li>
      <li>View</li>
      <li>Expire</li>
      <li>Message Send</li>
      <li>Message Receive</li>
      <li>Notification receive</li>
      <li>Run scheduled action</li>
      <li>Execute action</li>
      <li>Finish</li>
      <li>Dismiss</li>
      <li>Retry</li>
      <li>Abort</li>
      <li>Assign</li>
      <li>Unassign</li>
      <li>Hold</li>
      <li>Unhold</li>
    </ul>
  </Accordion>
</AccordionGroup>

* **Subject identifier** - the name related to the subject, there are different types of identifiers based on the selected subject

* **Version** - the version of the process definition at the time of the event

* **Status** - the outcome of the event (e.g. success or failure)

<Frame>
  ![Audit log overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/audit_log_new.png)
</Frame>

## Filtering

You can filter audit records by event date and by selecting specific options for User, Subject, and Subject Identifier.

* Filter by event date

<Frame>
  ![Audit filter by event date](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/audit_filter_by_event.png)
</Frame>

* **User** - single selection, type at least 4 characters
* **Subject** - single selection
* **Subject identifier** - exact match

## Audit log details

To view additional details for a specific event, click the eye icon on the right of the event in the list. Additional information available in the audit log details window includes
Here you have the following information:

* **Event** - the specific action that occured
* **URL** - the URL associated with the event
* **Body** - any additional data or information related to the event

<Frame>
  ![Audit log details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/audit_log_details.png)
</Frame>

<Card title="Audit setup" href="../../../setup-guides/audit-setup-guide" icon="files">
  More details on how to deploy Audit microservice
</Card>


# Configuration parameters
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/configuration-parameters

Manage variables and values that change across deployment environments (Development, QA, Production) without hardcoded updates.

<Info>
  Configuration Parameters are defined per **project version** or **library version**, ensuring consistency across builds while allowing for environment-specific overrides. These parameters can be used across various components, such as business rules, UI elements, integration designer, and gateways.

  Libraries can define configuration parameters to facilitate testing of processes or workflows that depend on them. However, unlike project-level configuration parameters, libraries do not support direct overrides.

  * Libraries provide default values for configuration parameters.
  * Projects using these libraries can override the provided values as required.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2018.45.32.png)
</Frame>

***

## Default and override values

* **Default Value**: Defined during parameter creation and included in the application build. It serves as the fallback value when no environment-specific override is set.
* **Override Value**: A value defined post-deployment for a specific environment. Overrides take precedence during runtime.
* **Precedence Behavior** (process variables override):
  * If a process variable and a configuration parameter share the same name, the process variable's value takes precedence during runtime.
  * If the process variable is null or undefined, the configuration parameter's value is used as a fallback.
  * Process variables override configuration parameters unless the process variable is `null` or undefined, in which case the configuration parameter is used.
* **Subprocess Behavior**:
  * When a value is passed to a subprocess, the subprocess uses the resolved value (process variable or configuration parameter) from the parent process.
  * If a new value is defined within the subprocess, it is appended back to the parent process.

<Tip>
  To avoid conflicts, use distinct names for process variables and generic parameters whenever possible.
</Tip>

<Info>
  **Exception in Business Rules**:\
  In business rules, values are taken directly from the map of configuration parameters without applying the above fallback logic.
</Info>

For details on configuring runtime overrides, see:

<Card title="Configuration Parameters Overrides" href="../../projects/runtime/configuration-parameters-overrides" icon="file" />

***

## Types of configuration parameters

Configuration parameters are defined as **key-value pairs** and support the following types:

### Value

A static value directly used by the project. Suitable for settings that do not change across environments.

* **Use Cases**:
  * Feature flags to toggle functionality (e.g., enabling/disabling insurance sales in a customer dashboard).
  * Email addresses for notification recipients.
  * Homebank redirect URLs for specific processes.

* **Example**:
  * **Key**: `officeEmail`
  * **Type**: `value`
  * **Value**: `officeEmail@office.com`

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-19%20at%2010.02.09.png)
</Frame>

***

### Environment variable

References an external value managed by DevOps. The stored value is the **environment variable name** that is resolved at runtime by looking it up in a configured **provider** (pod environment variables by default, or Kubernetes ConfigMaps).

* **Use Cases**:
  * Environment-specific API base URLs.
  * Dynamic configuration of services or integrations.

* **Example**:
  * **Key**: `baseUrl`
  * **Type**: `environment variable`
  * **Value**: `FLOWX_CONFIGPARAM_BASE_URL` (environment variable name resolved at runtime to an externally defined value)

<Warning>
  By default, only variables that match the regex pattern `FLOWX_CONFIGPARAM_.*` can be read at runtime. Variables that don't follow this naming convention will not be accessible, even if they are properly defined. See [Runtime access patterns](#runtime-access-patterns) for more details.
</Warning>

Configuration details:

| Key     | Type                   | Value                        | Description                                                  |
| ------- | ---------------------- | ---------------------------- | ------------------------------------------------------------ |
| baseUrl | `environment variable` | `FLOWX_CONFIGPARAM_BASE_URL` | A reference to the base URL configured externally by DevOps. |

**Example values for different environments**

| Environment | External Variable Name       | Actual Value                  |
| ----------- | ---------------------------- | ----------------------------- |
| Development | `FLOWX_CONFIGPARAM_BASE_URL` | `https://dev.example.com/api` |
| QA          | `FLOWX_CONFIGPARAM_BASE_URL` | `https://qa.example.com/api`  |
| Production  | `FLOWX_CONFIGPARAM_BASE_URL` | `https://api.example.com`     |

***

### Secret environment variable

References sensitive data (passwords, API keys, credentials) managed by DevOps. The value you enter is the **name of the environment variable** (e.g., `FLOWX_CONFIGPARAM_DB_PASSWORD`) that holds the actual secret. At runtime, FlowX resolves this name by looking it up in a dedicated secrets provider — separate from the one used for regular environment variables — so that sensitive values can be stored and accessed securely (e.g., via Kubernetes Secrets).

* **Use Cases**:
  * Passwords or tokens for integrations.
  * Secure configuration of external services in the integration designer.

* **Example**:
  * **Key**: `dbPassword`
  * **Type**: `secret environment variable`
  * **Value**: `FLOWX_CONFIGPARAM_DB_PASSWORD`

<Warning>
  Like environment variables, secret environment variables must also follow the regex pattern `FLOWX_CONFIGPARAM_.*` to be accessible at runtime. See [Runtime access patterns](#runtime-access-patterns) for more details.
</Warning>

### How environment variable and secret environment variable differ

Both types work the same way — they store an environment variable name that is resolved at runtime by a **provider**. The key difference is that each type uses a **separate provider**, which can be configured independently:

| Type                        | Provider setting                      | Default provider     | Kubernetes provider |
| --------------------------- | ------------------------------------- | -------------------- | ------------------- |
| Environment variable        | `FLOWX_CONFIGPARAMS_VARS_PROVIDER`    | `env` (pod env vars) | `k8s-configmaps`    |
| Secret environment variable | `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | `env` (pod env vars) | `k8s-secrets`       |

<Info>
  With the **default `env` provider**, both types resolve from pod environment variables — the only difference is that each type has its own allowlist regex (`FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX` vs `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX`), so operators can control which variables are accessible for each type.

  With **Kubernetes providers**, the distinction becomes more significant: environment variables read from **ConfigMaps** (plain text), while secret environment variables read from **Kubernetes Secrets** (Base64-encoded).
</Info>

For full provider configuration details, see the [FlowX Engine setup guide](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters) or the [Integration Designer setup guide](/5.9/setup-guides/integration-designer-setup#configuration-parameters).

***

## Use cases for configuration parameters

Configuration parameters simplify the management of environment-specific or dynamic settings across multiple project components:

1. **Business Rules**:
   * Define dynamic logic based on parameters such as feature toggles or environment-specific conditions.
   * Access configuration parameters directly from the `additionalData.applicationConfiguration` map.

<Info>
  For more information on how to use configuration parameters in business rules, see [Extracting values from configuration parameters](../../building-blocks/actions/business-rule-action/extracting-additional-data#extracting-values-from-configuration-parameters).
</Info>

2. **UI Elements**:
   * Configure content dynamically based on the environment (e.g., URLs for redirects, conditional features).
   * **Note**: Ensure variables referenced in UI components (e.g., for dynamic content or URLs) are uniquely named to avoid unexpected overrides by process variables.
3. **Integration Designer**:
   * Reference configuration parameters in system URLs, tokens, credentials, and other endpoint settings.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-19%20at%2010.40.02.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-19%20at%2010.41.41.png)
</Frame>

4. **Gateways**:
   * Dynamically manage routing and decision-making logic using environment-specific parameters.

5. **Workflow condition nodes**:
   * Use configuration parameters and user details in workflow Fork/Condition node expressions.
   * Access configuration parameters via `additionalData.applicationConfiguration` and user details via `additionalData.securityDetails`.

***

## Autocomplete support

Configuration parameters are surfaced through autocomplete in two places:

### Integration Designer fields

Fields that accept configuration parameters (base URLs, tokens, client IDs, and other system settings) provide a **searchable dropdown** when you type `$`:

* Type `$` to trigger autocomplete and see available configuration parameters
* Filter the list by typing the parameter key after `$`
* Select a parameter to insert it as `${paramKey}`
* If no matching parameter exists, select **Create new** to define a new configuration parameter inline without leaving the current screen

### Business rule code editors

The Monaco code editor in business rule actions provides **IntelliSense autocomplete** for configuration parameters. When typing `additionalData.applicationConfiguration.`, the editor shows all defined configuration parameters with their descriptions and values.

<Info>
  Sensitive parameters display masked values (`********`) in the autocomplete suggestions.
</Info>

***

## Adding a configuration parameter

To add a new configuration parameter:

1. Navigate to **Your Project** → **Configuration Parameters**.
2. Click **New Parameter** and provide the following:
   * **Key**: Name of the parameter.
   * **Type**: Select `value`, `environment variable`, or `secret environment variable`.
   * **Value**:
     * For `value`: Enter the static value.
     * For `environment variable` or `secret environment variable`: Enter a name following the agreed naming convention (must start with `FLOWX_CONFIGPARAM_` by default).
   * **Sensitive**: Toggle **ON** to mark this parameter as containing sensitive data. When enabled, the parameter's resolved value is masked (`********`) in engine debug logs. This flag is independent of the parameter type — any type can be marked as sensitive.
3. Click **Save** to include the parameter in the application build.

<Tip>
  Remember that environment variables and secret environment variables must follow the naming pattern `FLOWX_CONFIGPARAM_*` to be accessible at runtime. See [Runtime access patterns](#runtime-access-patterns) for more details.
</Tip>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2019.07.20.png)
</Frame>

***

## Runtime access patterns

FlowX.AI implements security controls to limit which environment variables and secrets can be accessed at runtime. This prevents unauthorized access to system variables and ensures only intended configuration parameters are readable by the application.

### Default regex pattern

By default, the FlowX Engine uses the regex pattern `FLOWX_CONFIGPARAM_.*` to filter which configuration parameters can be accessed at runtime. This means:

* **Environment variables** and **secret environment variables** must start with `FLOWX_CONFIGPARAM_` to be readable
* Variables that don't match this pattern will be ignored, even if properly defined in the environment
* This security measure prevents accidental access to system variables like `SPRING_*`, `JAVA_*`, or other sensitive environment variables

### Naming convention requirements

When defining environment variables or secret environment variables, follow this naming convention:

✅ **Correct naming:**

* `FLOWX_CONFIGPARAM_API_URL`
* `FLOWX_CONFIGPARAM_DB_PASSWORD`
* `FLOWX_CONFIGPARAM_EXTERNAL_SERVICE_TOKEN`

❌ **Incorrect naming (will not be accessible):**

* `API_URL`
* `DB_PASSWORD`
* `SERVICE_TOKEN`

<Frame>
  ![Configuration Parameters Regex Pattern](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/config_params_regex.png)
</Frame>

### Customizing the regex pattern

The default regex pattern can be overridden by configuring the following environment variables on the FlowX Engine:

| Environment Variable                        | Description                             | Default Value          |
| ------------------------------------------- | --------------------------------------- | ---------------------- |
| `FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX`    | Regex pattern for environment variables | `FLOWX_CONFIGPARAM_.*` |
| `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX` | Regex pattern for secret variables      | `FLOWX_CONFIGPARAM_.*` |

<Warning>
  Changing the default regex pattern should be done carefully and only by experienced DevOps teams. Using overly permissive patterns (like `.*`) can expose sensitive system variables to the application.
</Warning>

### Best practices for naming

1. **Always use the prefix**: Start all environment and secret variables with `FLOWX_CONFIGPARAM_`
2. **Use descriptive names**: Make variable names clear and specific to their purpose
3. **Follow consistent naming**: Use uppercase with underscores for environment variables
4. **Test accessibility**: Verify that your variables are accessible in your target environment before deployment

***

## Export and import

You can export and import configuration parameters to transfer them between projects or environments.

### Exporting

1. Navigate to **Your Project** > **Configuration Parameters**
2. Open the context menu and select **Export**
3. The parameters are downloaded as a ZIP file

### Importing

1. Navigate to **Your Project** > **Configuration Parameters**
2. Open the context menu and select **Import ZIP**
3. Select the ZIP file exported from another project or environment
4. If parameters with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting parameter (or use **Apply to all**):
   * **Keep both** - imports the parameter as a new copy alongside the existing one
   * **Replace** - overwrites the existing parameter with the imported version
   * **Skip this one** - keeps the existing parameter unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

***

## Technical notes and best practices

### Security

* **Sensitive values**: Mark parameters containing passwords, tokens, or credentials as **Sensitive** to ensure their values are masked in engine debug logs.
* **Secret environment variables**: Use the `secret environment variable` type for values that should be sourced from Kubernetes Secrets in production deployments.
* Avoid logging or exposing sensitive configuration parameter values in custom business rules or UI elements.

### Environment-specific updates

* Environment variable and secret environment variable updates are managed by DevOps.
* Updates may require service restarts unless a caching or real-time mechanism (e.g., change streams) is implemented.

### Reserved keys

* Certain keys are reserved for system use (e.g., `processInstanceId`). Avoid using reserved keys for custom configurations.

### Variable naming

* **Avoid Shared Names**:
  * Do not use the same name for configuration parameters and process variables to prevent unintentional overrides.
* **Fallback Logic Awareness**:
  * Understand that `null` or `undefined` process variables will default to the corresponding configuration parameter's value during runtime.
* **Subprocess Behavior**:
  * Variables in subprocesses are appended back to parent processes with their current state. Plan naming conventions and data flows accordingly.

<Warning>
  When designing processes, ensure that variables in subprocesses and parent processes do not conflict with configuration parameters names. Test these interactions in scenarios where variables are dynamically assigned or left undefined.
</Warning>

***


# FlowX.AI CMS
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/content-management

The FlowX.AI Headless Content Management System (CMS) is a core component of the FlowX.AI platform, designed to enhance the platform's capabilities with specialized functionalities for managing taxonomies and diverse content types.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/cms5.1.png)
</Frame>

## Key features

The FlowX.AI CMS offers the following features:

<CardGroup>
  <Card title="Enumerations" href="enumerations" icon="list">
    Manage and configure enumerations for various content types
  </Card>

  <Card title="Substitution tags" href="substitution-tags" icon="tags">
    Utilize tags to dynamically insert content values. Essential for Task Management localization with 51 system tags
  </Card>

  <Card title="Media library" href="media-library" icon="photo-film">
    Organize and manage media assets
  </Card>

  <Card title="Notification templates" href="notifications-plugin" icon="bell">
    Manage notification templates
  </Card>

  <Card title="Document templates" href="documents-plugin" icon="file">
    Manage document templates
  </Card>
</CardGroup>

## Enumeration sources

The FlowX.AI platform supports three types of enumeration sources:

* **Project-level enumerations**: Enumerations defined directly at the project level within the FlowX.AI Designer
* **Library enumerations**: Enumerations defined in a shared library that must be set as a dependency for the project
* **Data source enumerations**: Enumerations that come from external data sources when using the Enumeration Mapper feature

## Deployment and integration

The CMS can be rapidly deployed on your chosen infrastructure, preloaded with necessary taxonomies or content via a REST interface, and integrated with the FlowX Engine using Kafka events.

For deployment and configuration, refer to the:

<Card title="CMS setup guide" href="../../../../setup-guides/cms-setup" icon="files" />

## Using the CMS service

Once the CMS is deployed in your infrastructure, you can define and manage custom content types, such as lists with different values based on external systems, blog posts, and more.

### Kafka integration

You can use Kafka to translate and extract content values based on your defined languages and source systems. This is useful for:

* Extracting values from specific enumerations for UI components
* Sending data to other integrations that require different label formats
* Generating documents with localized content
* Handling different label conventions from various external systems

<Info>
  Various external systems and integrations might use different labels for the same information. In processes, it is easier to use the corresponding code and translate this into the needed label when necessary: for example when sending data to other integrations, when generating documents, etc.
</Info>

#### Kafka topics configuration

Manage content retrieval messages between the CMS and the FlowX Engine using the following Kafka topics:

| Environment Variable                | Default FlowX.AI value (customizable)                          | Purpose                                                              |
| ----------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- |
| KAFKA\_TOPIC\_REQUEST\_CONTENT\_IN  | ai.flowx.plugin.cms.trigger.retrieve.content.v1                | Topic where CMS listens for incoming content retrieval requests      |
| KAFKA\_TOPIC\_REQUEST\_CONTENT\_OUT | ai.flowx.engine.receive.plugin.cms.retrieve.content.results.v1 | Topic where CMS sends content retrieval results back to FlowX Engine |

<Tip>
  You can find the defined topics in two ways:

  1. In the FlowX.AI Designer: Go to **Platform Status** → **cms-core-mngt** → **kafkaTopicsHealthCheckIndicator** → **Details** → **Configuration** → **Topic** → **Request** → **Content** (use the `in` topic).

  ![Kafka Topics in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/kafka-translate-cms-topics.png)

  2. Alternatively, check the CMS microservice deployment for the `KAFKA_TOPIC_REQUEST_CONTENT_IN` environment variable.
</Tip>

#### Required Kafka headers

The following headers must be included in translation requests:

| Header                 | Required | Description                                        |
| ---------------------- | -------- | -------------------------------------------------- |
| `BUILD_APP_VERSION_ID` | Yes\*    | Application version build ID                       |
| `BUILD_ID`             | Yes\*    | Alternative to BUILD\_APP\_VERSION\_ID             |
| `WORKSPACE_ID`         | No       | Workspace identifier for multi-tenant environments |

<Warning>
  Either `BUILD_APP_VERSION_ID` or `BUILD_ID` must be provided in the Kafka message headers.
</Warning>

#### Translation request structure

Add a [**Send Message Task** (kafka send event)](../../../building-blocks/node/message-send-received-task-node) and configure it to send content requests to the FlowX.AI Engine.

##### Request parameters

| Parameter          | Type   | Required | Description                                                                |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------- |
| `sourceSystem`     | String | No\*     | Target source system for code translation                                  |
| `fromSourceSystem` | String | No\*     | Source system to translate codes from (cannot be used with `sourceSystem`) |
| `language`         | String | No\*     | Language code for label translation (e.g., "en", "fr", "ro")               |
| `replyTopic`       | String | No       | Custom Kafka topic for response (overrides default)                        |
| `entries`          | Array  | Yes      | List of content entries to translate                                       |

<Warning>
  **Validation rules:**

  * At least one of `sourceSystem`, `language`, or `fromSourceSystem` must be provided
  * `sourceSystem` and `fromSourceSystem` **cannot both be provided** (bidirectional conflict)
</Warning>

##### Entry structure

Each entry in the `entries` array contains:

| Parameter                        | Type   | Required | Description                                         |
| -------------------------------- | ------ | -------- | --------------------------------------------------- |
| `codes`                          | Array  | Yes      | Array of codes to translate                         |
| `contentDescription`             | Object | Yes      | Content metadata for lookup                         |
| `contentDescription.name`        | String | Yes      | Enumeration/content name                            |
| `contentDescription.application` | String | No       | Application name (defaults to `defaultApplication`) |
| `children`                       | Object | No       | Nested child content translations (hierarchical)    |

#### Example: Basic translation request

<video />

**Request Body:**

```json theme={"system"}
{
  "sourceSystem": "FlowX",
  "language": "fr",
  "entries": [
    {
      "codes": [
        "RO",
        "DE"
      ],
      "contentDescription": {
        "name": "tari"
      }
    }
  ]
}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/kafka-translate-cms.png)
</Frame>

#### Example: Hierarchical content request

For enumerations with nested/hierarchical structures (parent-child relationships), you can request content at multiple levels by specifying the `children` property. This is useful when you need to retrieve values from dependent dropdowns or cascading selections.

**Use cases:**

* Country → County → City selections
* Product Category → Subcategory → Product
* Department → Team → Employee
* Any cascading dropdown scenario

**Request Body for Hierarchical Content:**

```json theme={"system"}
{
  "language": "ro",
  "sourceSystem": "FlowX",
  "entries": [
    {
      "codes": [
        "RO"
      ],
      "contentDescription": {
        "name": "tari"
      },
      "children": {
        "RO": [
          {
            "code": "AB",
            "children": [
              {
                "code": "AB-Abrud"
              },
              {
                "code": "AB-Aiud"
              }
            ]
          },
          {
            "code": "BV",
            "children": [
              {
                "code": "BV-Brasov"
              }
            ]
          }
        ]
      }
    }
  ]
}
```

**Key points for hierarchical requests:**

* The `children` property is an object where **keys represent parent codes** and values are arrays of child items
* Each child item must have a `code` property and can optionally have a nested `children` array for deeper hierarchies
* This allows you to request specific branches of hierarchical data rather than entire enumerations
* Content metadata (name, application) is inferred from parent-child relationships configured in CMS
* Unlimited nesting depth is supported for complex hierarchical structures

<Tip>
  **Best practice:** Request only the levels needed for the current UI state rather than the entire hierarchy upfront. Use progressive loading (parent → selected child → grandchild) for better performance.
</Tip>

#### Translation types

The CMS translation service supports multiple types of translations:

<Tabs>
  <Tab title="Language Translation">
    **Purpose:** Translate codes to human-readable labels in specific languages

    **Request:**

    ```json theme={"system"}
    {
      "language": "en",
      "entries": [
        {
          "codes": ["RO"],
          "contentDescription": {"name": "country"}
        }
      ]
    }
    ```

    **Response:**

    ```json theme={"system"}
    {
      "entries": [
        {
          "contentName": "country",
          "code": "RO",
          "label": "Romania",
          "translatedCode": null
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Source System Translation">
    **Purpose:** Translate codes to target source system format

    **Request:**

    ```json theme={"system"}
    {
      "sourceSystem": "SAP",
      "entries": [
        {
          "codes": ["RO"],
          "contentDescription": {"name": "country"}
        }
      ]
    }
    ```

    **Response:**

    ```json theme={"system"}
    {
      "entries": [
        {
          "contentName": "country",
          "code": "RO",
          "label": null,
          "translatedCode": "RO-SAP"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Combined Translation">
    **Purpose:** Get both language labels and source system codes

    **Request:**

    ```json theme={"system"}
    {
      "language": "en",
      "sourceSystem": "SAP",
      "entries": [
        {
          "codes": ["RO"],
          "contentDescription": {"name": "country"}
        }
      ]
    }
    ```

    **Response:**

    ```json theme={"system"}
    {
      "entries": [
        {
          "contentName": "country",
          "code": "RO",
          "label": "Romania",
          "translatedCode": "RO-SAP"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Reverse Translation">
    **Purpose:** Translate from external source system code to internal code

    **Request:**

    ```json theme={"system"}
    {
      "fromSourceSystem": "SAP",
      "language": "en",
      "entries": [
        {
          "codes": ["RO-SAP"],
          "contentDescription": {"name": "country"}
        }
      ]
    }
    ```

    **Response:**

    ```json theme={"system"}
    {
      "entries": [
        {
          "contentName": "country",
          "code": "RO",
          "label": "Romania",
          "translatedCode": null
        }
      ]
    }
    ```
  </Tab>
</Tabs>

#### Translation response structure

Add a **Receive Message Task** to handle the response from the CMS service. Configure it to listen to the topic where the Engine sends the response (e.g., `ai.flowx.updates.contents.values.v1`).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/kafka-translate-cms-response.png)
</Frame>

**Response Message Structure:**

```json theme={"system"}
{
  "entries": [
    {
      "contentName": "country",
      "code": "ROMANIA",
      "label": "Romania",
      "translatedCode": "ROMANIA-FlowX"
    },
    {
      "contentName": "country",
      "code": "BAHAMAS",
      "label": "Bahamas",
      "translatedCode": "BAHAMAS-FlowX"
    }
  ],
  "error": null
}
```

**Response fields:**

| Field                      | Type   | Description                                                         |
| -------------------------- | ------ | ------------------------------------------------------------------- |
| `entries`                  | Array  | List of translated content entries                                  |
| `entries[].contentName`    | String | Name of the content/enumeration                                     |
| `entries[].code`           | String | Original code value                                                 |
| `entries[].label`          | String | Translated label based on language parameter                        |
| `entries[].translatedCode` | String | Code translated for source system (format: `{code}-{sourceSystem}`) |
| `entries[].children`       | Object | Nested translated child content (for hierarchical requests)         |
| `error`                    | String | Error message (null if successful)                                  |

**Response for hierarchical content:**

```json theme={"system"}
{
  "entries": [
    {
      "contentName": "countries",
      "code": "RO",
      "label": "România",
      "translatedCode": "RO-FlowX",
      "children": {
        "AB": [
          {
            "contentName": "counties",
            "code": "AB",
            "label": "Alba",
            "translatedCode": "AB-FlowX",
            "children": [
              {
                "contentName": "cities",
                "code": "AB-Abrud",
                "label": "Abrud",
                "translatedCode": "AB-Abrud-FlowX"
              }
            ]
          }
        ]
      }
    }
  ],
  "error": null
}
```

#### Dynamic language switching example

<Frame>
  <video />
</Frame>

The video demonstrates how to change the system language and modify your process to display translations dynamically on different screens.

#### Advanced features

##### Custom reply topics

You can override the default response topic by specifying a `replyTopic` parameter in your request:

```json theme={"system"}
{
  "language": "en",
  "replyTopic": "ai.flowx.custom.translate.response.v1",
  "entries": [
    {
      "codes": ["RO"],
      "contentDescription": {"name": "country"}
    }
  ]
}
```

This is useful for:

* Process-specific handling
* Asynchronous workflows
* Custom routing logic

<Warning>
  Ensure the Engine is configured to listen on custom reply topics before using this feature.
</Warning>

##### Build context and versioning

The CMS translation service uses build context headers to ensure correct content version resolution:

* `BUILD_APP_VERSION_ID` or `BUILD_ID` ensures translation uses the correct content version
* Critical for environments with multiple application versions running simultaneously
* Resolves content from build manifest resource overrides
* Ensures consistent translations across deployments

##### Resource overrides

The translation service supports content overrides via build manifest, enabling:

* Version-specific translations
* Multi-tenant workspace configurations
* Environment-specific content variations
* A/B testing with different content versions

#### Performance considerations

<AccordionGroup>
  <Accordion title="Batch Multiple Codes">
    Request multiple codes in a single Kafka message to reduce overhead:

    ```json theme={"system"}
    {
      "language": "en",
      "entries": [
        {
          "codes": ["RO", "DE", "FR", "IT", "ES"],
          "contentDescription": {"name": "country"}
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Use Hierarchical Children">
    Request parent and child content together to minimize round trips:

    ```json theme={"system"}
    {
      "language": "en",
      "entries": [
        {
          "codes": ["RO"],
          "contentDescription": {"name": "country"},
          "children": {
            "RO": [{"code": "AB"}, {"code": "BV"}]
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Cache Translated Values">
    Store translated values in process data when they will be reused multiple times within the same process instance.
  </Accordion>

  <Accordion title="Progressive Loading">
    For deep hierarchies, load levels progressively based on user selections rather than requesting entire hierarchies upfront.
  </Accordion>
</AccordionGroup>

#### Error handling

Common translation errors:

| Error                   | Description                                         | Resolution                                                |
| ----------------------- | --------------------------------------------------- | --------------------------------------------------------- |
| Content not found       | The specified content/enumeration does not exist    | Verify content name and ensure it's published in CMS      |
| Invalid source system   | The source system is not configured                 | Check source system configuration in CMS                  |
| Missing required fields | Required parameters are missing from request        | Ensure `codes` and `contentDescription.name` are provided |
| Build context missing   | Required headers not present                        | Include `BUILD_APP_VERSION_ID` or `BUILD_ID` in headers   |
| Validation conflict     | Both `sourceSystem` and `fromSourceSystem` provided | Use only one direction of translation per request         |

**Error response structure:**

```json theme={"system"}
{
  "entries": [],
  "error": "Content 'invalid_content_name' not found"
}
```

<Info>
  When translation fails, the `error` field contains a descriptive message and the `entries` array may be empty or contain partial results.
</Info>

## Additional resources

<CardGroup>
  <Card title="Enumerations" href="enumerations" icon="list">
    Learn how to configure enumerations in CMS
  </Card>

  <Card title="CMS Setup Guide" href="../../../../setup-guides/cms-setup" icon="gear">
    Complete deployment and configuration guide
  </Card>
</CardGroup>


# Combining files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/combining-files

You can combine multiple files into a single document using the Documents plugin.

This guide provides step-by-step instructions on how to combine multiple files into a single PDF document, such as when a user needs to merge several related documents into one file.

## Prerequisites

1. **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

   * **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the combining process, ensure you have the unique IDs of all files you want to combine in the storage solution. This ensures that the combination is performed on already uploaded files.

<Check>
  Ensure that all files to be combined are PDF documents. The combine operation merges multiple PDF files into a single PDF.
</Check>

You have two options to obtain file IDs:

* Extract the file ID from a [**Response Message**](./uploading-a-new-document#response-message-example-2) of an upload file request. For more details, refer to the [**upload process documentation**](./uploading-a-new-document).

* Extract the file ID from a [**Response Message**](./generating-from-html-templates#receiving-the-document-generation-reply) of a generate from template request. For more details, refer to the [**document generation reply documentation**](./generating-from-html-templates).

<Info>
  In the following example, we will combine two documents using their `fileId` values obtained from previous upload operations.

  **File 1:**

  ```json theme={"system"}
  {
    "customId": "119501",
    "fileId": "0b453429-6807-4439-9a14-46222d70620c",
    "documentType": "APPLICATION_FORM",
    "documentLabel": null,
    "minioPath": "flowx-dev-process-id-119501/119501/470_APPLICATION_FORM.pdf",
    "downloadPath": "internal/files/0b453429-6807-4439-9a14-46222d70620c/download",
    "noOfPages": 12,
    "error": null
  }
  ```

  **File 2:**

  ```json theme={"system"}
  {
    "customId": "119501",
    "fileId": "0da982f6-e167-4e4b-9c71-459e3fca429b",
    "documentType": "APPENDIX",
    "documentLabel": null,
    "minioPath": "flowx-dev-process-id-119501/119501/471_APPENDIX.pdf",
    "downloadPath": "internal/files/0da982f6-e167-4e4b-9c71-459e3fca429b/download",
    "noOfPages": 3,
    "error": null
  }
  ```
</Info>

## Configuring the combining process

To create a process that combines multiple files into a single document, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-send-task-node) node and a [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-receive-task-node) node:

* Use the **Send Message Task** node to send the combine request.
* Use the **Receive Message Task** node to receive the combine reply.

2. Configure the **first node (Send Message Task)** by adding a **Kafka Send Action**.

3. Specify the [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup#file-combination) where you want to send the combine request.

<Tip>
  To identify your defined topics in your current environment, follow the next steps:

  1. From the FLOWX.AI main screen, navigate to the Platform Status menu at the bottom of the left sidebar.
  2. In the FLOWX Components list, scroll to the document-plugin-mngt line and press the eye icon on the right side.
  3. In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → file → combine**. Here you will find the in and out topics for combining files.
</Tip>

4. Fill in the body of the message request.

#### Message request example

```json theme={"system"}
{
  "combineFiles": [
    {
      "documentType": "CONTRACT",
      "customId": "119501",
      "files": [
        {
          "fileId": "0b453429-6807-4439-9a14-46222d70620c",
          "startPage": 0,
          "endPage": 11,
          "order": 0
        },
        {
          "fileId": "0da982f6-e167-4e4b-9c71-459e3fca429b",
          "startPage": 0,
          "endPage": 2,
          "order": 1
        }
      ],
      "shouldOverride": true
    }
  ]
}
```

* **combineFiles**: An array of combine operations. Each operation creates one combined document.
  * **documentType**: The document type to assign to the combined file.
  * **customId**: The unique identifier for the combined document (it could be for example the ID of a client or process instance).
  * **files**: An array of files to include in the combined document:
    * **fileId**: The unique identifier of the file to include.
    * **startPage**: Starting page number (0-indexed). Use `0` for the first page.
    * **endPage**: Ending page number (0-indexed). Use `0` to include only the first page, or specify a higher number to include a range.
    * **order**: The order in which files should be combined. Files are merged in ascending order based on this value.
  * **shouldOverride**: A boolean value indicating whether to override an existing document if one with the same name already exists.

<Warning>
  **Page numbering is 0-indexed.** Setting both `startPage: 0` and `endPage: 0` will include only the first page of that file. To include all pages from a 12-page document, use `startPage: 0` and `endPage: 11`.
</Warning>

<Info>
  You can combine specific page ranges from different documents. For example, you could take pages 1-3 from document A and pages 5-10 from document B.
</Info>

5. Configure the **second node (Receive Message Task)** by adding a Data stream topic:

<Info>
  The response will be sent to the `..out` Kafka topic configured for file combination.
</Info>

## Receiving the reply

The following values are expected in the reply body:

* **customId**: The unique identifier for your document (matching the name of the folder in the storage solution where the document is uploaded).
* **fileId**: The ID of the newly created combined file.
* **documentType**: The document type.
* **documentLabel**: The document label (if available).
* **minioPath**: The storage path for the combined document.
* **downloadPath**: The download path for the combined document.
* **noOfPages**: The total number of pages in the combined document.
* **error**: Any error message in case of an error during the combining process.

#### Message response example

```json theme={"system"}
{
  "customId": "119501",
  "fileId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "documentType": "CONTRACT",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119501/119501/472_CONTRACT.pdf",
  "downloadPath": "internal/files/c3d4e5f6-a7b8-9012-cdef-345678901234/download",
  "noOfPages": 15,
  "error": null
}
```

The combined file is now available in the storage solution and can be downloaded. The total page count reflects the sum of included pages from all source documents based on your specified page ranges.

<Info>
  Note that the actual values in the response will depend on the specific combine request and the documents being combined.
</Info>


# Converting files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats

Convert documents between formats using the Documents Plugin. Supports PDF to JPEG conversion and on-the-fly CSV/Excel (including macro-enabled .xlsm) to JSON conversion on download.

The Documents Plugin supports two types of file conversion:

* **PDF to JPEG** — converts an uploaded PDF into JPEG images via Kafka messaging
* **CSV/Excel to JSON** — converts CSV, XLS, XLSX, or XLSM files to structured JSON on-the-fly when downloading, using content negotiation (no new files are stored)

***

## CSV/Excel to JSON conversion

You can download CSV or Excel files as structured JSON directly from the file download endpoints. The conversion happens on-the-fly — no new files are created in storage.

To request JSON output, set the `Accept` header to `application/json` when calling either of these endpoints:

* `GET /internal/files/{fileId}/download`
* `GET /internal/storage/download`

### Supported file types

| Content type                                                        | Extensions |
| ------------------------------------------------------------------- | ---------- |
| `text/csv`                                                          | `.csv`     |
| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `.xlsx`    |
| `application/vnd.ms-excel`                                          | `.xls`     |
| `application/vnd.ms-excel.sheet.macroEnabled.12`                    | `.xlsm`    |

<Info>
  `.xlsm` (macro-enabled Excel) is supported, but macros themselves are not executed — only the tabular data is read.
</Info>

### Query parameters

| Parameter | Type     | Default     | Description                                                                                                                                     |
| --------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `format`  | `string` | `objects`   | Output shape: `objects` (array of key-value maps using the header row as keys) or `arrays` (array of arrays including headers as the first row) |
| `sheet`   | `string` | First sheet | For Excel files, the name of the sheet to convert. If omitted, the first sheet is used                                                          |

### Example

```bash theme={"system"}
curl -H "Accept: application/json" \
  "https://{your-document-url}/internal/files/{fileId}/download?format=objects"
```

Given a CSV file:

```csv theme={"system"}
name,age,city
Alice,30,New York
Bob,25,London
```

**`format=objects`** returns:

```json theme={"system"}
[
  {"name": "Alice", "age": "30", "city": "New York"},
  {"name": "Bob", "age": "25", "city": "London"}
]
```

**`format=arrays`** returns:

```json theme={"system"}
[
  ["name", "age", "city"],
  ["Alice", "30", "New York"],
  ["Bob", "25", "London"]
]
```

### Behavior

* If the file is already JSON, the raw content is passed through unchanged.
* If the file is not a supported tabular format (for example, PDF), the endpoint returns **406 Not Acceptable**.
* If no `Accept: application/json` header is sent, the file downloads as raw bytes — preserving existing behavior.

***

## PDF to JPEG conversion

<Info>
  The PDF to JPEG conversion uses Kafka messaging and creates a new file in storage, unlike the on-the-fly CSV/Excel to JSON conversion described above.
</Info>

This section provides step-by-step instructions on how to convert an uploaded file from PDF to JPEG.

## Prerequisites

1. **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

* **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the conversion process, it is essential to identify the file in the storage solution using its unique ID. This ensures that the conversion is performed on an already uploaded file.

You have two options to obtain the file ID:

* Extract the file ID from a [**Response Message**](./uploading-a-new-document) of an upload file request. For more details, refer to the [**upload process documentation**](./uploading-a-new-document).

* Extract the file ID from a [**Response Message**](./generating-from-html-templates) of a generate from template request. For more details, refer to the [**document generation reply documentation**](./generating-from-html-templates)

<Info>
  In the following example, we will use the `fileId` generated for [**Uploading a New Document**](./uploading-a-new-document) scenario.

  ```json theme={"system"}
  {
    "customId": "119246",
    "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
    "documentType": "BULK",
    "documentLabel": null,
    "minioPath": "flowx-dev-process-id-119246/119246/458_BULK.pdf",
    "downloadPath": "internal/files/96975e03-7fba-4a03-99b0-3b30c449dfe7/download",
    "noOfPages": null,
    "error": null
  }
  ```
</Info>

## Configuring the process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_pdf_to_jpeg.png)

To create a process that converts a document from PDF to JPEG format, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) node and a [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node):

* Use the **Send Message Task** node to send the conversion request.
* Use the **Receive Message Task** node to receive the reply.

2. Configure the first node (**Send Message Task**) by adding a **Kafka send action**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_action_name.png)

3. Specify the [**Kafka topic**](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#kafka-configuration) where you send the conversion request.

<Tip>
  To identify your defined topics in your current environment, follow the next steps:

  1. From the FLOWX.AI main screen, navigate to the **Platform Status** menu at the bottom of the left sidebar.
  2. In the FLOWX Components list, scroll to the **document-plugin-mngt** line and press the eye icon on the right side.
  3. In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → file → convert**. Here will find the in and out topics for converting files.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kakfa_topics_convert.png)
</Tip>

4. Fill in the body of the message request.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_action.png)

#### Message request example

<Info>
  This is an example of a message that follows the custom integration data model.
</Info>

```json theme={"system"}
{
  "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
  "to": "image/jpeg"
}
```

* `fileId`: The file ID that will be converted
* `to`: The file extension to convert to (in this case, "JPEG")

5. Configure the second node (**Receive Message Task**) by adding a **Data stream topic**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_stream.png)

<Info>
  The response will be sent to this `..out` Kafka topic.
</Info>

## Receiving the reply

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_response.png)

The following values are expected in the reply body:

* **customId**: The unique identifier for your document (it could be for example the ID of a client)
* **fileId**: The file ID
* **documentType**: The document type
* **documentLabel**: The document label (if available)
* **minioPath**: The path where the converted file is saved. It represents the location of the file in the storage system, whether it's a MinIO path or an S3 path, depending on the specific storage solution
* **downloadPath**: The download path for the converted file
* **noOfPages**: If applicable
* **error**: Any error message in case of an error during the conversion process

#### Message response example

```json theme={"system"}
{
  "customId": "119246",
  "fileId": "8ec75c0e-eaa6-4d80-b7e5-15a68bba7459",
  "documentType": "BULK",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119246/119246/461_BULK.jpg",
  "downloadPath": "internal/files/461/download",
  "noOfPages": null,
  "error": null
}
```

The converted file is now available in the storage solution and it can be downloaded:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/jpg_final.png)

<Info>
  Note that the actual values in the response will depend on the specific conversion request and the document being converted.
</Info>


# Deleting files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/deleting-a-file

The Documents plugin provides functionality for deleting files.

## How files get deleted

Files in the Documents Plugin can be deleted in two ways:

<CardGroup>
  <Card title="Explicit deletion" icon="trash">
    Using the Kafka delete action described below to manually delete a specific file by its `fileId` and `customId`.
  </Card>

  <Card title="Implicit deletion (replacement)" icon="rotate">
    When uploading a new file with the **same `customId` AND `documentType`** combination as an existing file, the previous file is automatically marked as deleted.
  </Card>
</CardGroup>

<Info>
  **Understanding implicit deletion**

  The implicit deletion behavior ensures that each `customId` + `documentType` combination points to only one active file. When you upload a new file with an existing combination:

  * The previous file is marked as deleted in the database
  * The previous file's download URLs stop working
  * The new file becomes the active document for that combination

  This is by design and useful for scenarios where you want to replace documents (e.g., updating a profile photo or replacing a draft contract). However, if you need to store multiple files of the same type, ensure each has a **unique `customId`**.
</Info>

## Prerequisites

Before deleting files, ensure:

1. **Access Permissions**: Ensure that the user account used has the necessary access rights for updates or deletions.

2. **Kafka Configuration**:

* **Verify Kafka Setup**: Ensure proper configuration and accessibility of the Kafka messaging system.
* **Kafka Topics**: Understand the Kafka topics used for these operations.

3. **File IDs and Document Types**: Prepare information for updating or deleting files:

* `fileId`: ID of the file to delete.
* `customId`: Custom ID associated with the file.

<Info>
  In the example below, we use a `fileId` generated for a document using [<u>**Uploading a New Document**</u>](./uploading-a-new-document) scenario.

  ```json theme={"system"}
  {
    "docs": [
      {
        "customId": "119407",
        "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2",
        "documentType": "BULK",
        "documentLabel": null,
        "minioPath": "flowx-dev-process-id-119408/119407/466_BULK.pdf",
        "downloadPath": "internal/files/c4e6f0b0-b70a-4141-993b-d304f38ec8e2/download",
        "noOfPages": 2,
        "error": null
      }
    ],
    "error": null
  }
  ```
</Info>

## Configuring the deletion process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_file_proc.png)

To delete files, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) node and [**Message Event Receive (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-receive-task-node) node:

* Use the **Send Message Task** node to send the delete request.
* Use the **Receive Message Task** node to receive the delete reply.

2. Configure the **first node (Send Message Task)** by adding a **Kafka Send Action**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_file_action.png)

3. Specify the [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup) for sending the delete request.

<Tip>
  To identify defined topics in your environment:

  * Navigate to **Platform Status > FLOWX Components > document-plugin-mngt** and click the eye icon on the right side.
  * In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → file → delete**. Here will find the in and out topics for deleting files.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_topics.png)
</Tip>

4. Fill in the request message body.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_request_message.png)

#### Message request example

Example of a message following the custom integration data model:

```json theme={"system"}
{
  "customId": "119408",
  "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2"
}
```

* **fileId**: The ID of the file.
* **customId**: The custom ID.

5. Configure the **second node (Receive Message Task)** by adding a Data stream topic:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_stream.png)

<Info>
  The response will be sent to `..out` Kafka topic.
</Info>

### Receiving the reply

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_response.png)

The reply body should contain the following values:

* **customId**: The unique identifier for your document (it could be for example the ID of a client)
* **fileId**: The ID of the file
* **documentType**: The document type
* **error**: Any error message in case of an error during the deleting process

#### Message response example

```json theme={"system"}
{
  "customId": "119408",
  "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2",
  "documentType": null,
  "error": null
}
```


# Document Templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview

You can add Document Templates to your custom FlowX.AI deployment to enhance the core platform capabilities with functionality specific to document handling.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_templates_ex.png)
</Frame>

The Document Templates feature offers the following features:

* **Document storage and editing**: Easily store and make changes to documents.
* **Document generation**: Generate documents using predefined templates and custom process-related data.
* **WYSIWYG editor**: Create various templates using a user-friendly ["What You See Is What You Get" (WYSIWYG) editor](../../wysiwyg).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_template_edit.png)
</Frame>

* **Template export and import**: Transfer templates between projects or environments using ZIP files.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_templates_import.png)
</Frame>

To import document templates:

1. Open the context menu on the Document Templates list page and select **Import from ZIP**
2. Select the ZIP file exported from another environment
3. If templates with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
4. Choose a strategy for each conflicting template (or use **Apply to all**):
   * **Keep both** - imports the template as a new copy alongside the existing one
   * **Replace** - overwrites the existing template with the imported version
   * **Skip this one** - keeps the existing template unchanged
5. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

* **Document conversion**: Convert documents from PDF to JPEG format.
* **Document splitting**: Split bulk documents into smaller separate documents.
* **Document editing**: Add generated barcodes, signatures, and assets to documents.
* **OCR integration**: When a document requires OCR (Optical Character Recognition) processing, the Documents Plugin initiates the interaction by passing the document data or reference to the [**OCR plugin**](../ocr-plugin).

You can deploy the Documents Plugin on your chosen infrastructure, preloaded with industry-specific document templates using an intuitive WYSIWYG editor, and connected to the FLOWX Engine through Kafka events.

* [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#message-send-task)
* [**Receive Message Task(Kafka)**](../../../../building-blocks/node/message-send-received-task-node#message-receive-task)

<Info>
  Performance considerations:

  To ensure optimal performance while using Document Templates, consider the following recommendations:

  * For large or complex documents, it is recommended to allocate sufficient system resources, such as CPU and memory, to handle the conversion/editing process efficiently.
  * Avoid processing extremely large files or a large number of files simultaneously, as it may impact performance and responsiveness.
  * Monitor system resources during the generating/editing/converting etc. process and scale resources as needed to maintain smooth operations.
  * Following these performance considerations will help optimize the document processing and improve overall system performance.
</Info>

## Using Document Templates

Once you have deployed the Document Templates microservice in your infrastructure, you can start creating various document templates. After selecting a document template, proceed to create a process definition by including [**Send Message/Receive Message**](../../../../building-blocks/node/message-send-received-task-node) (Kafka nodes) and custom document-related actions in your process flow.

Before adding these actions to your **process definition**, follow these steps:

1. Ensure that all custom information is properly configured in the plugin, such as the document templates to be used.
2. For each Kafka send/receive node you will need a corresponding Kafka topic.

<Check>
  The `..in` topic names configured for the plugin should match [**the `..out` topic  names used when configuring the engine**](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka). Make sure to use an outgoing topic name that matches the pattern configured in the Engine. The value can be found and overwritten in the `KAFKA_TOPIC_PATTERN` variable.

  For more information, see the [Process Engine Kafka topic configuration](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka).

  To make a request to the Document Templates microservice, the process definition needs to include an action of type **Kafka send** defined on a [**Send Message Task**](../../../../building-blocks/node/message-send-received-task-node#message-send-task) node. The action parameter should have the key `topicName` and the corresponding topic name as its value.

  To receive a reply from the Document Templates microservice, the process definition needs to include a [**Receive Message Task**](../../../../building-blocks/node/message-send-received-task-node#message-receive-task) node with a node value having the key `topicName` and the topic name as its value.
</Check>

Once the setup is complete, you can begin adding custom actions to your processes.

Let's explore a few examples that cover both the configuration and integration with the engine for all the use cases supported by the plugin:

<CardGroup>
  <Card title="Generating documents based on templates" href="generating-from-html-templates" icon="file" />

  <Card title="Uploading a new document" href="uploading-a-new-document" icon="upload" />

  <Card title="Converting documents to different formats" href="converting-documents-to-different-formats" icon="files" />

  <Card title="Splitting a document" href="splitting-a-document" icon="scissors" />

  <Card title="Combining files" href="combining-files" icon="object-group" />

  <Card title="Deleting a file" href="deleting-a-file" icon="trash" />

  <Card title="Getting URLs to documents" href="getting-urls-to-documents" icon="link" />

  <Card title="Listing stored documents" href="listing-stored-files" icon="list" />
</CardGroup>


# Encrypting and decrypting files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files

Learn how to encrypt and decrypt files using the Documents plugin via Kafka messaging.

## Overview

The Documents plugin provides file encryption and decryption capabilities through Kafka messaging. This feature allows you to:

* **Encrypt files** - Password-protect one or multiple files stored in the Documents plugin
* **Decrypt files** - Unlock password-protected files and extract contents from encrypted ZIP archives

Both operations are triggered via Kafka messages. Internal HTTP endpoints are also available for testing purposes.

### Supported file types

| Format          | Extensions      |
| --------------- | --------------- |
| PDF             | `.pdf`          |
| Microsoft Word  | `.doc`, `.docx` |
| Microsoft Excel | `.xls`, `.xlsx` |
| ZIP             | `.zip`          |

<Info>
  When encrypting multiple files, they are automatically bundled into a password-protected ZIP archive. During decryption, ZIP archives are extracted and only files matching supported types are returned.
</Info>

## Prerequisites

Before using the encryption/decryption features, ensure:

<Check>The Documents plugin is deployed and configured in your environment</Check>
<Check>Files are already uploaded to the Documents plugin (you'll need file IDs)</Check>
<Check>Kafka topics are properly configured</Check>

## Kafka topics

The encryption and decryption operations use dedicated Kafka topics for communication between the FlowX Engine and the Documents plugin.

### Topic configuration

| Environment Variable                    | Default Topic Name                                                | Direction | Description                   |
| --------------------------------------- | ----------------------------------------------------------------- | --------- | ----------------------------- |
| `KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_IN`  | `ai.flowx.plugin.document.trigger.encrypt.file.v1`                | Inbound   | Topic for encryption requests |
| `KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_IN`  | `ai.flowx.plugin.document.trigger.decrypt.file.v1`                | Inbound   | Topic for decryption requests |
| `KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_OUT` | `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Outbound  | Topic for encryption results  |
| `KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_OUT` | `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Outbound  | Topic for decryption results  |

<Tip>
  To find the configured topic names in your environment:

  1. Navigate to **FlowX Designer → Platform Status**
  2. Locate **document-plugin-mngt** in the components list
  3. Click the eye icon and expand **KafkaTopicsHealthCheckIndicator → details → configuration → topic → document**
</Tip>

***

## Encrypting files

Use file encryption to password-protect documents stored in the Documents plugin.

### How encryption works

1. The plugin validates that all specified file(s) exist
2. Validates that files are of supported types
3. Downloads the file(s) from storage
4. Creates a password-protected copy:
   * **Single file**: Creates an encrypted copy with a new file ID
   * **Multiple files**: Creates a ZIP archive containing all files, then password-protects the ZIP
5. Returns the file ID of the encrypted document

### Request message structure

Configure a **Send Message Task** node with a Kafka Send action to trigger file encryption.

**Topic**: Use the encryption inbound topic (e.g., `ai.flowx.plugin.document.trigger.encrypt.file.v1`)

**Request body**:

```json theme={"system"}
{
  "fileIds": ["file-id-1", "file-id-2"],
  "password": "your-secure-password"
}
```

| Parameter  | Type             | Required | Description                                                                         |
| ---------- | ---------------- | -------- | ----------------------------------------------------------------------------------- |
| `fileIds`  | Array of strings | Yes      | List of file IDs to encrypt (files must exist in Documents plugin)                  |
| `password` | String           | No       | Password for encryption. If null, creates an unprotected archive for multiple files |

### Response message structure

Configure a **Receive Message Task** node to receive the encryption result.

**Topic**: Use the encryption outbound topic (e.g., `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1`)

**Response body**:

```json theme={"system"}
{
  "status": "success",
  "message": null,
  "fileId": "encrypted-file-id-123"
}
```

| Parameter | Type   | Description                                                             |
| --------- | ------ | ----------------------------------------------------------------------- |
| `status`  | String | Operation result: `success`, `partial_success`, `error`, or `no-op`     |
| `message` | String | Additional information (populated in case of errors or partial success) |
| `fileId`  | String | The file ID of the newly created encrypted file                         |

### Example: Encrypt a single file

<Steps>
  <Step title="Add a Send Message Task node">
    Configure a Kafka Send action with the encryption topic and the following message body:

    ```json theme={"system"}
    {
      "fileIds": ["${uploadedDocument.fileId}"],
      "password": "${encryptionPassword}"
    }
    ```
  </Step>

  <Step title="Add a Receive Message Task node">
    Configure the node to listen on the encryption results topic to capture the encrypted file ID.
  </Step>

  <Step title="Store the encrypted file ID">
    Use the response `fileId` for subsequent operations (e.g., sending via email, downloading).
  </Step>
</Steps>

***

## Decrypting files

Use file decryption to unlock password-protected documents and extract contents from encrypted archives.

### How decryption works

1. The plugin validates that the specified file exists
2. Validates that the file is of a supported type
3. Downloads the file from storage
4. Attempts to open the file:
   * First tries without a password
   * If that fails, uses the provided password
5. If the file is a ZIP archive, extracts its contents
6. Filters extracted files by supported types
7. Uploads the resulting file(s) to storage
8. Returns the file ID(s) of the decrypted/extracted files

### Request message structure

Configure a **Send Message Task** node with a Kafka Send action to trigger file decryption.

**Topic**: Use the decryption inbound topic (e.g., `ai.flowx.plugin.document.trigger.decrypt.file.v1`)

**Request body**:

```json theme={"system"}
{
  "fileId": "encrypted-file-id-123",
  "password": "your-secure-password"
}
```

| Parameter  | Type   | Required | Description                                                                      |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `fileId`   | String | Yes      | The file ID of the encrypted file to decrypt                                     |
| `password` | String | No       | Password for decryption. If the file is not password-protected, this can be null |

### Response message structure

Configure a **Receive Message Task** node to receive the decryption result.

**Topic**: Use the decryption outbound topic (e.g., `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1`)

**Response body**:

```json theme={"system"}
{
  "status": "success",
  "message": null,
  "fileIds": ["decrypted-file-id-1", "decrypted-file-id-2"]
}
```

| Parameter | Type             | Description                                                             |
| --------- | ---------------- | ----------------------------------------------------------------------- |
| `status`  | String           | Operation result: `success`, `partial_success`, `error`, or `no-op`     |
| `message` | String           | Additional information (populated in case of errors or partial success) |
| `fileIds` | Array of strings | List of file IDs for the decrypted/extracted files                      |

<Note>
  When decrypting a ZIP archive, the response contains multiple file IDs—one for each extracted file that matches supported file types.
</Note>

### Example: Decrypt a password-protected file

<Steps>
  <Step title="Add a Send Message Task node">
    Configure a Kafka Send action with the decryption topic and the following message body:

    ```json theme={"system"}
    {
      "fileId": "${encryptedDocument.fileId}",
      "password": "${userProvidedPassword}"
    }
    ```
  </Step>

  <Step title="Add a Receive Message Task node">
    Configure the node to listen on the decryption results topic.
  </Step>

  <Step title="Process the decrypted files">
    The response `fileIds` array contains all successfully decrypted files. Use these IDs for further document processing.
  </Step>
</Steps>

***

## Error handling

Both encryption and decryption operations return descriptive error messages when issues occur.

### Common error scenarios

| Scenario              | Status            | Description                                                                     |
| --------------------- | ----------------- | ------------------------------------------------------------------------------- |
| All files processed   | `success`         | All files were encrypted/decrypted successfully                                 |
| Some files failed     | `partial_success` | Some files were processed but others failed (e.g., unsupported type in a batch) |
| File not found        | `error`           | The specified file ID does not exist in the Documents plugin                    |
| Unsupported file type | `error`           | The file format is not supported for encryption/decryption                      |
| Invalid password      | `error`           | The provided password is incorrect (decryption only)                            |
| No files to process   | `no-op`           | Empty file list provided or all files filtered out                              |

### Example error response

```json theme={"system"}
{
  "status": "error",
  "message": "File with ID 'invalid-id-123' not found",
  "fileId": null
}
```

<Warning>
  Always implement error handling in your process flow to gracefully manage encryption/decryption failures. Check the `status` field before proceeding with subsequent operations.
</Warning>

***

## Security considerations

<CardGroup>
  <Card title="Password handling" icon="key">
    In the current version, passwords are transmitted in clear text. Ensure your Kafka communication is secured with TLS encryption.
  </Card>

  <Card title="File storage" icon="database">
    Encrypted files are stored as new documents with unique file IDs. Original files remain unchanged.
  </Card>
</CardGroup>

***

## Related documentation

<CardGroup>
  <Card title="Documents plugin overview" icon="file" href="../documents-plugin-overview">
    Learn about all Documents plugin capabilities
  </Card>

  <Card title="Documents plugin setup" icon="gear" href="/setup-guides/documents-plugin-setup">
    Configure the Documents plugin in your environment
  </Card>

  <Card title="Uploading files" icon="upload" href="./uploading-a-new-document">
    Upload files to the Documents plugin before encryption
  </Card>

  <Card title="Kafka Send action" icon="paper-plane" href="/docs/building-blocks/actions/kafka-send-action">
    Configure Kafka Send actions in your process
  </Card>
</CardGroup>


# Generating documents
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates

Generate new documents from custom templates that can be pre-filled with data from the current process instance.

<Info>
  Configure document templates using the [**WYSIWYG editor**](../../wysiwyg). Access and manage your templates through the **Document Templates** section in your Project in [**FlowX Designer**](../../../../flowx-designer/overview).
</Info>

<Frame>
  ![Document template interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/docs_plugin_template.png)
</Frame>

## Generating documents from HTML templates

The Documents plugin simplifies document generation through predefined templates. This guide focuses on generating documents using HTML templates.

<Frame>
  ![Document templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_tmplts.png)
</Frame>

## Before you begin

1. **Verify access permissions**: Ensure you have the necessary [permissions to manage document templates](../../../../../setup-guides/access-management/workspaces-access-rights).
2. **Check Kafka configuration**: Confirm that Kafka is properly configured and accessible:
   * The document plugin relies on Kafka for communication between nodes
   * Familiarize yourself with the required Kafka topics (detailed later in this guide)

## Creating an HTML template

1. Access the [**WYSIWYG editor**](../../../plugins/wysiwyg) through **FlowX Designer → Plugins → Document templates**
2. Create or import your HTML template

<Frame>
  ![HTML template creation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_template.png)
</Frame>

For detailed template management instructions:

<Card title="Managing HTML templates" href="./managing-html-templates" icon="files" />

<Tip>
  For comprehensive guidance, take our FlowX.AI Academy course: [**Creating a Document Template in Designer**](https://academy.flowx.ai/module/create-document-templates-flowxai-designer).
</Tip>

# Implementing document generation in a process

Let's build a document generation flow that creates personalized documents based on user input:

<Frame>
  ![Document generation process example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_upload_prev_ex.png)
</Frame>

### Step 1: Create a user input form

1. Add a **User Task** node to your process
2. Configure UI elements to collect the information needed for your document:
   * Input fields (text, numbers, dates, etc.)
   * Make sure to set appropriate keys for each field that match your template variables

<video />

### Step 2: Configure the document generation request

1. Add a **Send Message Task (Kafka)** node
2. Configure the Kafka send action with the appropriate topic:
   * For HTML template generation, use `ai.flowx.in.document.html.in` (or your configured equivalent)

<Frame>
  ![Kafka send action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gen_template_action.png)
</Frame>

<Tip>
  To find your environment's configured topics:

  1. Navigate to **FlowX Designer → Platform Status**
  2. Find the **document-plugin-mngt** component and click the eye icon
  3. Expand `KafkaTopicsHealthCheckIndicator → details → configuration → topic → document → generate`
  4. Look under HTML and PDF sections for your in/out topics

  ![Kafka topics for document generation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_topics_html_generate.png)
</Tip>

3. Create the request payload with the following structure:

```json theme={"system"}
{ 
  "documentList": [
    {
      "customId": "ClientsFolder",
      "templateName": "AccountCreation",
      "language": "en",
      "data": {
        "firstInput": "${application.client.firstName}",
        "secondInput": "${application.client.lastName}",
        "thirdInput": "${application.client.accountType}"
      },
      "includeBarcode": false
    }
  ]
}
```

<Frame>
  ![Kafka send action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gen_templ_payload.png)
</Frame>

Key parameters:

* **customId**: Folder name where the file will be saved
* **templateName**: Name of the template defined in Document templates
* **language**: Must match the language configured on the template
* **data**: Key-value pairs mapping template variables to process data
* **includeBarcode**: Set to true if you need a barcode on the document

<Info>
  When using templates in a process, the system uses default values from the default project language. For example, if English is your default project language, the template will use values from the English version.

  To check your default language: **FlowX Designer → Project Settings → Languages**
</Info>

### Step 3: Receive the generated document

1. Add a **Receive Message Task (Kafka)** node
2. Configure it with:
   * The response topic: `ai.flowx.updates.document.html.generate.v1` (or your configured equivalent)
   * Key for storing the response: `generatedDocuments`

<Frame>
  ![Receive message configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/generate_template_receive.png)
</Frame>

The response contains information about the generated documents:

<Frame>
  ![HTML generation response](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/html_generated_response.png)
</Frame>

Sample response structure:

```json theme={"system"}
{
  "generatedFiles": {
    "ClientsFolder": {
      "AccountCreation": {
        "customId": "ClientsFolder",
        "fileId": "320f4ec2-a509-4aa9-b049-87224594802e",
        "documentType": "AccountCreation",
        "documentLabel": "GENERATED_PDF",
        "minioPath": "{{your_bucket}}/2024/2024-01-15/process-id-865759/ClientsFolder/6869_AccountCreation.pdf",
        "downloadPath": "internal/files/320f4ec2-a509-4aa9-b049-87224594802e/download",
        "noOfPages": 1,
        "error": null
      }
    }
  },
  "error": null
}
```

Response fields:

* **fileId**: Unique identifier for the generated file
* **documentType**: Template name used for generation
* **minioPath**: Storage location (MinIO or S3)
* **downloadPath**: URL path for downloading the file
* **noOfPages**: Document page count
* **error**: Error information (null if successful)

## Displaying the generated document

To display the generated document to the user:

1. Add a **Task Node** to extract the document path from the response
2. Add a **User Task** with the File Preview UI Element:
   * Configure the element with the download path from the previous node

For detailed instructions on displaying documents, see:

<Card title="Uploading a new document" href="./uploading-a-new-document" icon="file" />


# Getting URLs
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/getting-urls-to-documents

In certain scenarios, obtaining URLs pointing to uploaded documents for use in integrations is essential. This process involves adding a custom action to your workflow that requests URLs from the Documents plugin.

## Prerequisites

Before retrieving document URLs, ensure:

1. **Access Permissions**: Ensure that the user account has the necessary access rights.

2. **Kafka Configuration**:

* **Verify Kafka Setup**: Ensure proper configuration and accessibility of the Kafka messaging system.
* **Kafka Topics**: Understand the Kafka topics used for these operations.

3. **Document Types**: Prepare information for updating or deleting files:

* `types`: A list of document types.

## Configuring the getting URLs process

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls.png)
</Frame>

To obtain document URLs, follow these steps:

<Steps>
  <Step title="Create the process">
    Create a process that will contain the following types of nodes:

    * [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) - used to send the get URLs request
    * [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) - used to receive the get URLs reply
    * [**User Task**](../../../../building-blocks/node/user-task-node) - where you will perform the upload action
  </Step>

  <Step title="Configure the User Task">
    Start configuring the **User Task** node:

    #### Node Config

    * **Data stream topics**: Add the topic where the response will be sent; in this example `ai.flowx.updates.document.html.persist.v1` and its key: `uploadedDocument`.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls1.png)
    </Frame>

    #### Actions

    We will configure the following node actions:

    * Upload File action ("uploadDocument") will have two child actions:
      * Send Data to User Interface ("uploadDocumentSendToInterface")
      * Business Rule ("uploadDocumentBR")
    * Save Data action ("save")

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_document_actions.png)
    </Frame>
  </Step>

  <Step title="Upload action parameters">
    Configure the parameters for the **Upload Action**:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_action_get_urls.png)
    </Frame>

    <Info>
      For more details on uploading a document and configuring the file upload child actions, refer to the following sections:

      * [**Upload document**](./uploading-a-new-document)
      * [**Upload action**](../../../../building-blocks/actions/upload-file-action)
    </Info>
  </Step>

  <Step title="Configure the Send Message Task">
    Next, configure the **Send Message Tas (Kafka)** node by adding a **Kafka Send Action** and specifying the `..in` [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup#kafka-configuration) to send the request.

    <Tip>
      Identify defined topics in your environment:

      * Navigate to **Platform Status > FlowX Components > document-plugin-mngt**  and press the eye icon on the right side.
      * In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → document → get**. Here will find the in and out topics for getting URLs for documents.

      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/get_urls_kafka.png)
    </Tip>
  </Step>

  <Step title="Configure the request action">
    Fill in the body of the request message for the Kafka Send action to send the get URLs request:

    <Frame>
      ![Request Message](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls2.png)
    </Frame>

    * `types`: A list of document types.

    #### Message request example

    Example of a message following the custom integration data model:

    ```json theme={"system"}
    {
      "types": [
        "119435",
        "119435"
      ]
    }
    ```
  </Step>

  <Step title="Configure the Receive Message Task">
    Configure the [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-receive-task-node) by adding the `..out` Kafka topic on which the response will be sent.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls3.png)
    </Frame>
  </Step>
</Steps>

## Receiving the reply

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls4.png)
</Frame>

The response body should include the following values:

* **success**: A boolean indicating whether the document exists and the URL was generated successfully.
* **fullName**: The full name of the document file, including the directory path.
* **fileName**: The name of the document file without the extension.
* **fileExtension**: The extension of the document file.
* **url**: The full download URL for the document.

#### Message response example

```json theme={"system"}
[
  {
    "success": true,
    "fullName": "2024/2024-08-27/process-id-1926248/1234_1926248/7715_1926248.pdf",
    "fileName": "2024/2024-08-27/process-id-1926248/1234_1926248/7715_1926248",
    "fileExtension": "pdf",
    "url": "http://minio:9000/qualitance-dev-paperflow-devmain/2024/2024-08-27/process-id-1926248/1234_1926248/7715_1926248.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=minio%2F20240827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240827T150257Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=575333697714249e9deb295359f5ba9365f618f53303bf5583ca30a9b1c45d84"
  }
]
```


# Listing stored files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/listing-stored-files

View files stored in S3-compatible buckets (such as MinIO or Amazon S3) using the Documents Plugin REST API.

To determine the partitioning strategy used for storing generated documents, you can access the following key in the configuration:

`application.file-storage.partition-strategy`

```yaml theme={"system"}
application:
  defaultLocale: en
  supportedLocales: en, ro
  #fileStorageType is the configuration that activates one FileContentService implementation. Valid values: minio / fileSystem
  file-storage:
    type: s3
    disk-directory: MS_SVC_DOCUMENT
    partition-strategy: NONE

```

The `partition-strategy` property can have two possible values:

* **NONE**: Documents are saved in separate buckets for each process instance. Each process instance has its own dedicated bucket.
* **PROCESS\_DATE**: Documents are saved in a single bucket with a subfolder structure based on the process date. For example: `bucket/2022/2022-07-04/process-id-xxxx/customer-id/file.pdf`.

## REST API

The Documents Plugin provides the following REST API endpoints for interacting with the stored files:

### List buckets

<Check>
  Check out the [**List buckets API reference**](../../../../api/storage/list-buckets) for more details.
</Check>

* This endpoint returns a list of available buckets.

### List objects in a bucket

<Check>
  Check out the [**List objects in a bucket API reference**](../../../../api/storage/list-objects-in-buckets) for more details.
</Check>

* This endpoint retrieves a list of objects stored within a specific bucket. Replace `BUCKET_NAME` with the actual name of the desired bucket

### Download file

<Check>
  Check out the [**Download file API reference**](../../../../api/storage/download-file) for more details.
</Check>

* This endpoint allows you to download a file by specifying its path or key.


# Managing templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/managing-html-templates

The Documents plugin provides the flexibility to define and manage HTML templates for document generation, enabling customization through various parameter types.

Additionally, the platform incorporates a [**What You See Is What You Get (WYSIWYG)**](../../wysiwyg) editor, allowing users to have a real-time, visual representation of the document or content during the editing process. Furthermore, you have the capability to test and review your template by downloading it as a PDF.

<Tip>
  A WYSIWYG editor, typically provides two main views:

  * **Design View (Visual View)**: In this view, you can see a visual representation of their content as it would appear when rendered in a web browser or other output medium. It resembles the final output closely, allowing you to format text, add images, and apply styles directly within the visual interface. This view aims to provide a real-time preview of the document's appearance.

  * **HTML View (Source View)**: In this view, you can see and edit the underlying HTML code that corresponds to the content displayed in the Design View. It shows the raw HTML markup, providing a more detailed and technical representation of the document. You can manually edit the HTML code to make precise adjustments or to implement features not available in the visual interface.
</Tip>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/wysiwyg_example.gif)

Explore the different parameter types and their specifications:

## Configuring HTML templates

In the following example, we will create an example of a template using the HTML View (Source View).

To create a document template, navigate to the **Document Templates** section in the **Designer**, select ”**New document**” from the menu in the top-right corner, name your template, and click **Create**.

Now follow the next steps to design a new template:

1. **Open the WYSIWYG editor**:

Access the WYSIWYG editor within the Document Management Plugin, found in the **FlowX Designer → Plugins → Document templates** section.

* **Language Configuration**: Create a dedicated template for each language specified in your system.

<Check>
  To confirm the installed languages on the platform, go to **FLOWX.AI Designer → Content Management → Languages**.
</Check>

2. **Design the document header**:

Begin by creating a header section for the document, including details such as the company logo and title.

```html theme={"system"}
<!-- Source: -->
<header>
   <img src="https://d22tnnndi9lo60.cloudfront.net/devmain/flowx/flowxlogo/1669299027205_FLOWX.AI%20main%20logo.png" alt="Company Logo" width="150px" height="auto">
   <h1 th:text="${offerTitle}">Offer Document</h1>
</header>
```

Data specifications (process data):

```json theme={"system"}
"data": {
    "companyLogo": "INSERT_BASE64_IMAGE",
    "offerTitle": "Client Offer"
}

```

3. **Text Parameters for Client Information**:

Include a section for client-specific information using text parameters.

<Info>
  Text parameters enable the inclusion of dynamic text in templates, allowing for personalized content.
</Info>

```html theme={"system"}
<!-- Source: -->
<section>
<h2>Client Information</h2>

<p><strong>Client Name:</strong> <span th:text="${clientName}"></span></p>

<p><strong>Client ID:</strong> <span th:text="${clientId}"></span></p>
</section>

<section>
```

Data specifications:

```json theme={"system"}
"data": {
    "clientName": "John Doe",
    "clientId": "JD123456"
}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/client_infor.png)
</Frame>

4. **Dynamic table for offer details:**

Create a dynamic table to showcase various details of the offer.

```html theme={"system"}
<!-- Source: -->
<section>
<h2>Offer Details</h2>

<table>
	<thead>
		<tr>
			<th>Item</th>
			<th>Description</th>
			<th>Price</th>
		</tr>
	</thead>
	<tbody>
		<tr th:each="item : ${offerItems}">
			<td th:text="${item.name}"></td>
			<td th:text="${item.description}"></td>
			<td th:text="${item.price}"></td>
		</tr>
	</tbody>
</table>
</section>
```

Data specifications:

```json theme={"system"}
"data": {
    "offerItems": [
        { "name": "Product A", "description": "Description A", "price": "$100" },
        { "name": "Product B", "description": "Description B", "price": "$150" },
        { "name": "Product C", "description": "Description C", "price": "$200" }
    ]
}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/table_offer.png)
</Frame>

5. **Dynamic sections for certain conditions:**

Dynamic sections allow displaying specific content based on certain conditions. For example, you can display a paragraph only when a certain condition is met.

```html theme={"system"}
<!-- Source: -->
<section>
<h2>Dynamic Sections for Certain Conditions</h2>
<span th:if="${isPreferredClient}"> </span>

<p><span th:if="${isPreferredClient}">This is displayed if it is a preferred client. They are eligible for special discounts!&nbsp;</span></p>
<span th:if="${isPreferredClient}"> </span> <span th:if="${hasSpecialRequest}"> </span>

<p><span th:if="${hasSpecialRequest}">This is displayed if the client has specific requests. Please review them carefully.</span></p>
<span th:if="${hasSpecialRequest}"> </span> <span th:if="${isActiveContract}"> </span>

<p><span th:if="${isActiveContract}">This is displayed if the client has an active contract with us.</span></p>
<span th:if="${isActiveContract}"> </span></section>
```

Data specifications:

```json theme={"system"}
"data": {
    "clientName": "John Doe",
    "clientId": "JD123456",
    "isPreferredClient": false,
    "hasSpecialRequest": false,
    "isActiveContract": true
}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/display_conditions.png)
</Frame>

6. **Lists**:

Lists are useful for displaying values from selected items in a checkbox as a bulleted list.

```html theme={"system"}
<!-- Source: -->
<section>
<div th:if="${incomeSource != null}">
<h3>Income source:</h3>

<ul>
	<li th:each="item : ${incomeSource}" th:text="${item}"></li>
</ul>
</div>
</section>
```

Data specifications:

```json theme={"system"}
{
    "data": {
        "incomeSource": [
            "Income 1",
            "Income 2",
            "Income 3",
            "Income 4"
        ]
    }
}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/list_html.png)
</Frame>

7. **Include Image for Authorized Signature:**

Embed an image for the authorized signature at the end of the document.

```html theme={"system"}
<!-- Source: -->
<footer>
<p>Authorized Signature:</p>
<img alt="Authorized Signature" height="auto" th:src="*{'data:image/png;base64,' + signature}" width="200px"></footer>
```

Data Specifications:

```json theme={"system"}
"data": {
    "signature": "INSERT_BASE64_IMAGE"
}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/authorized_sign.png)
</Frame>

8. **Barcodes**:

Set the `includeBarcode` parameter to true if you want to include a barcode. For information on how to use barcodes and OCR plugin, check the following section:

<Card title="OCR plugin" href="../ocr-plugin" />

9. **Checkboxes for Consent**:

Consent checkboxes in HTML templates are commonly used to obtain explicit agreement or permission from users before proceeding with certain actions or processing personal data.

```html theme={"system"}
<!--Source:-->
    <section>
        <label for="consent-checkbox">
            <input type="checkbox" id="consent-checkbox" name="consent" value="consent">
            I consent to the terms and conditions.
        </label>
    </section>
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/checkbox_html.gif)
</Frame>

10. **Data Model**:

In the documents template we have the **Data Model** tab. Here you define parameters, which are dynamic data fields that will be replaced with the values you define in the payload, like first name, or company name.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/data_model_input.png)

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dataModelTemplate.png)
</Frame>

## Styling

HTML template styling plays a crucial role in enhancing the visual appeal, readability, and user experience of generated documents.

<Warning>
  The PDF generation engine only supports **CSS 2.1**. Modern CSS features such as Flexbox, Grid, CSS variables, and advanced selectors are not supported. Ensure your styles are compatible with CSS 2.1 specifications.
</Warning>

We will apply the following styling to the previously created HTML template using **Source** view of the editor.

```css theme={"system"}
	<style type="text/css">body {
            font-family: 'Arial', sans-serif;
            margin: 20px;
            color: #343a40;
        }

        header {
            text-align: center;
        }

        header img {
            width: 150px;
            height: auto;
        }

        h1 {
            color: #000; /* Adjust color as needed */
            margin-top: 10px;
        }

        h2 {
            color: #fdb913;
            margin-bottom: 10px;
            font-size: 1.2em; /* Adjust font size as needed */
        }

        p {
            margin-bottom: 10px;
            font-size: 1em; /* Adjust font size as needed */
        }

        table {
            width: 100%;
            border-collapse: collapse;
            margin-bottom: 20px;
        }

        th, td {
            border: 1px solid #ddd;
            padding: 8px;
            text-align: left;
        }

        th {
            background-color: #f2f2f2;
        }

        ul {
            list-style-type: disc;
            margin-left: 20px;
            color: #6c757d;
        }

        footer {
            margin-top: 20px;
        }
	</style>
```

In the end the template will look like this:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/manage_template_final.png)

## Samples

### Without dynamic data

The final result after generating the template without dynamic data:

<Info>
  Download the [PDF sample](../../../assets/HTMLExample.pdf).
</Info>

### With dynamic data

The final result after generating the template with the following dummy process data:

```json theme={"system"}
"data": {
    "offerTitle": "Client Offer",
    "clientName": "John Doe",
    "clientId": "JD123456",
    "isPreferredClient": false,
    "hasSpecialRequest": false,
    "isActiveContract": true,

    "offerItems": [
        { "name": "Product A", "description": "Description A", "price": "$100" },
        { "name": "Product B", "description": "Description B", "price": "$150" },
        { "name": "Product C", "description": "Description C", "price": "$200" },
    ],
     "incomeSource": [
            "Income 1",
            "Income 2",
            "Income 3",
            "Income 4"
        ],
}
```

<Tip>
  Download a [PDF sample](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/726_ManageHTMLTemplate%20.pdf).
</Tip>


# Splitting documents
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/splitting-a-document

You can split a document into multiple parts using the Documents plugin.

This guide provides step-by-step instructions on how to split a document, such as when a user uploads a bulk scanned file that needs to be separated into distinct files.

## Prerequisites

1. **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

* **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the splitting process, ensure you have the unique ID of the file in the storage solution. The system performs the splitting on an already uploaded file.

<Check>
  Ensure that the uploaded document contains more than one file.
</Check>

You have two options to obtain the file ID:

* Extract the file ID from a [**Response Message**](./uploading-a-new-document#response-message-example-2) of an upload file request. For more details, refer to the [**upload process documentation**](./uploading-a-new-document).

* Extract the file ID from a [**Response Message**](./generating-from-html-templates#receiving-the-document-generation-reply) of a generate from template request. For more details, refer to the [**document generation reply documentation**](./generating-from-html-templates).

<Info>
  In the following example, we will use the `fileId` generated for a document with multiple files using [**Uploading a New Document**](./uploading-a-new-document) scenario.

  ```json theme={"system"}
  {
    "customId": "119407",
    "fileId": "446c69fb-32d2-44ba-a0b2-02dbb55e7eea",
    "documentType": "BULK",
    "documentLabel": null,
    "minioPath": "flowx-dev-process-id-119407/119407/465_BULK.pdf",
    "downloadPath": "internal/files/446c69fb-32d2-44ba-a0b2-02dbb55e7eea/download",
    "noOfPages": null,
    "error": null
  }
  ```
</Info>

## Configuring the splitting process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_document.png)

To create a process that splits a document into multiple parts, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-send-task-node) node and a [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-receive-task-node) node:

* Use the **Send Message Task** node to send the splitting request.
* Use the **Receive Message Task** node to receive the splitting reply.

2. Configure the **first node (Send Message Task)** by adding a **Kafka Send Action**.

3. Specify the [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup#kafka-configuration) where you want to send the splitting request.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/kafka_split_topic.png)
</Frame>

<Tip>
  To identify your defined topics in your current environment, follow the next steps:

  1. From the FLOWX.AI main screen, navigate to the Platform Status menu at the bottom of the left sidebar.
  2. In the FLOWX Components list, scroll to the document-plugin-mngt line and press the eye icon on the right side.
  3. In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → document → split**. Here you will find the in and out topics for splitting documents.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_topics_split.png)
</Tip>

4. Fill in the body of the message request.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_kafka_action.png)
</Frame>

#### Message request example

```json theme={"system"}
{
  "parts": [
    {
      "documentType": "BULK",
      "customId": "119407",
      "pagesNo": [
        1,
        2
      ],
      "shouldOverride": true
    }
  ],
  "fileId": "446c69fb-32d2-44ba-a0b2-02dbb55e7eea"
}
```

* **fileId**: The file ID of the document that will be split
* **parts**: A list containing information about the expected document parts
  * **documentType**: The document type.
  * **customId**: The unique identifier for your document (it could be for example the ID of a client)
  * **shouldOverride**: A boolean value (true or false) indicating whether to override an existing document if one with the same name already exists
  * **pagesNo**: The pages that you want to separate from the document

5. Configure the **second node (Receive Message Task)** by adding a Data stream topic:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_response_kafka.png)
</Frame>

<Info>
  The response will be sent to this `..out` Kafka topic.
</Info>

## Receiving the reply

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_response.png)
</Frame>

The following values are expected in the reply body:

* **docs**: A list of documents.
  * **customId**: The unique identifier for your document (matching the name of the folder in the storage solution where the document is uploaded).
  * **fileId**: The ID of the file.
  * **documentType**: The document type.
  * **minioPath**: The storage path for the document.
  * **downloadPath**: The download path for the document.
  * **noOfPages**: The number of pages in the document.
* **error**: Any error message in case of an error during the splitting process.

Here's an example of the response JSON:

#### Message response example

```json theme={"system"}
{
  "docs": [
    {
      "customId": "119407",
      "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2",
      "documentType": "BULK",
      "documentLabel": null,
      "minioPath": "flowx-dev-process-id-119408/119407/466_BULK.pdf",
      "downloadPath": "internal/files/c4e6f0b0-b70a-4141-993b-d304f38ec8e2/download",
      "noOfPages": 2,
      "error": null
    }
  ],
  "error": null
}
```

The split document is now available in the storage solution and can be downloaded:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/2024-01-30%2013.39.35.gif)


# Creating and uploading a new document
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document

A comprehensive guide to integrating document creation from templates, managing uploads, and configuring workflows for document processing.

<Info>
  User task nodes provide a flexible framework to defining and configuring UI templates and actions for specific template config nodes, such as an upload file button.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/docs_upload_proc_4.5.png)
</Frame>

## Prerequisites

Before you begin, ensure the following prerequisites are met:

* **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.
* **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

  * **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section).

<Warning>
  **Important: Document replacement behavior**

  When uploading a file with the **same `customId` AND `documentType` combination** as an existing document, the previous document will be automatically **marked as deleted** and replaced by the new file.

  This means:

  * The previous file's URLs will stop working
  * Only the most recent file with that `customId` + `documentType` combination will be accessible

  **Best practices:**

  * Always use **unique, dynamic values** for `customId` (e.g., `${processInstanceId}`, client ID, or a generated UUID)
  * Do not copy examples with hardcoded values like `customId: "1234"` without changing them to unique values
  * If you need to store multiple documents of the same type for the same entity, ensure each has a unique identifier

  ```json Example: Using dynamic values theme={"system"}
  {
    "customId": "${processInstanceId}",  // or use a client-specific ID
    "documentType": "CONTRACT",
    "tempFileId": "..."
  }
  ```
</Warning>

To upload a document using this process, follow the steps outlined below.

## Step-by-step guide: uploading an previewing a document

In the [previous section](./generating-from-html-templates), you learned how to generate documents from HTML templates. This section focuses on creating a process where users can generate a document, review and sign it, and subsequently upload it.

<Frame>
  <video />
</Frame>

### Process overview

This process involves several key nodes, each performing specific tasks to ensure smooth document creation, preview, and upload:

* **Start and End Nodes**: These nodes mark the beginning and end of the process, respectively.
* **User Task Node**: Collects user input necessary for document generation.
* **Send and Receive Message Tasks (Kafka)**: Handle communication with Kafka for generating the document and retrieving it after processing.
* **Service Task Node**: Appends the path of the generated document to the process, enabling further actions.
* **User Task Nodes**: Facilitate the preview of the generated document and manage the upload of the signed document.

## Configuring the process

<Steps>
  <Step title="Document generation">
    Follow the steps outlined in [**Generating from HTML templates**](./generating-from-html-templates) configure the document generation part of the process.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_upload_prev_ex.png)
    </Frame>

    <Info>
      If you only need to upload a new file without generating it from templates, skip the template generation steps.
    </Info>

    After configuration, your request and response messages should resemble the examples below.

    #### Request message example

    This JSON structure represents a Kafka message sent through the `..in` topic to initiate a request in the Process Engine. It includes information for generating an "AccountCreation" document with a custom ID "119237" in English. Data specifies client details extracted dynamically from user input (first name, last name, age, country) and company information (name, registration date).

    <Info>
      This an example of a message that follows the custom integration data model.
    </Info>

    ```json theme={"system"}
    {
      "documentList": [
        {
          "customId": "119246", //this will match the name of the folder in the storage solution
          "templateName": "AccountCreation",
          "language": "en",
          "data": {
            "application": {
              "client": {
                "firstName": "John",
                "lastName": "Doe",
                "age": "33",
                "country": "AU"
              },
              "company": {
                "name": "ACME",
                "registrationDate": "24.01.2024"
              }
            }
          },
          "includeBarcode": false
        }
      ]
    }
    ```

    #### Response message example

    This JSON structure represents the response received on the `..out` Kafka topic, where the Process Engine expects a reply. It contains details about the generated PDF file corresponding to the custom ID "119237" and the "AccountCreation" template. The response provides file-related information such as file ID, document type, document label, storage path, download path, number of pages, and any potential errors (null if none). The paths provided in the response facilitate access and download of the generated PDF file.

    ```json theme={"system"}
    {
      "generatedFiles": {
        "119246": {
          "AccountCreation": {
            "customId": "119246",
            "fileId": "f705ae5b-f301-4700-b594-a63b50df6854",
            "documentType": "AccountCreation",
            "documentLabel": "GENERATED_PDF",
            "minioPath": "flowx-dev-process-id-119246/119246/457_AccountCreation.pdf", // path to the document in the storage solution
            "downloadPath": "internal/files/f705ae5b-f301-4700-b594-a63b50df6854/download", //link for download
            "noOfPages": 1,
            "error": null
          }
        }
      },
      "error": null
    }
    ```
  </Step>

  <Step title="Preview document">
    Configure the **preview** part of the process.

    <Frame>
      ![Preview and Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/preview_path.png)
    </Frame>

    #### Service task node

    We will configure the service task node to construct the file path for the generated document.

    Configure a business rule to construct a file path for the generated document. Ensure the base admin path is specified.

    <Check>
      Ensuring the base admin path is specified is crucial, as it grants the required administrative rights to access the endpoint responsible for document generation.
    </Check>

    #### Actions

    **Action Edit**

    * **Action Type**: Set to **Business Rule**
    * **Trigger Type**: Choose **Automatic** because is not a user-triggered action
    * **Required Type**: Set as **Mandatory**

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/create_document_path.png)
    </Frame>

    **Parameters**

    * **Language**: We will use **MVEL** for this example
    * **Body Message**: Fill in the body message request

    ```js theme={"system"}
    adminPath = "https://admin-main.playground.flowxai.dev/document/";
    processInstanceId = input.?generatedDocuments.?generatedFiles.keySet().toArray()[0];
    downloadPath = input.?generatedDocuments.?generatedFiles.?get(processInstanceId).Company_Client_Document.downloadPath;

    if(downloadPath != null){
        output.put("generatedDocuments", {
            "filePath" : adminPath + downloadPath
        });
    }
    ```

    <Accordion title="Explanation of MVEL code">
      * **adminPath**: Base URL for the admin path.

      ```java theme={"system"}
      adminPath = "https://admin-main.playground.flowxai.dev/document/";
      ```

      * **processInstanceId**: Extracts the process instance ID from the input. Assumes an input structure with a generatedDocuments property containing a generatedFiles property. Retrieves the keys, converts them to an array, and selects the first element.

      ```java theme={"system"}
      processInstanceId = input.?generatedDocuments.?generatedFiles.keySet().toArray()[0];
      ```

      * **downloadPath**: Retrieves the downloadPath property using the obtained processInstanceId.

      ```java theme={"system"}
      downloadPath = input.?generatedDocuments.?generatedFiles.?get(processInstanceId).Company_Client_Document.downloadPath;`
      ```

      * **if condition**: Checks if downloadPath is not null and constructs a new object in the output map.

      ```java theme={"system"}
      if(downloadPath != null){
          output.put("generatedDocuments", {
              "filePath" : adminPath + downloadPath
          });
      }
      ```
    </Accordion>

    ### User Task

    Now we will configure the user task to preview the generated document.

    #### Actions

    Configure the **Actions edit** section:

    * **Action Type**: Set to **Save Data**.
    * **Trigger Type**: Choose **Manual** to allow user-triggered action.
    * **Required Type**: Set as **Mandatory**.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/document_preview_action.png)
    </Frame>

    Let's see what we have until now.

    The screen where you can fill in the client details:

    ![Client Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_fill_data.gif)

    The screen where you can preview and download the generated document:

    ![Preview Document](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/preview_document_vis.gif)
  </Step>

  <Step title="Upload document">
    Configure the user task where we will upload the signed document genereated from the previous document template.

    #### Node Config

    * **Swimlane**: Choose a swimlane (if multiple) to restrict access to specific user roles.
    * **Stage**: Assign a stage to the node.
    * **Data stream topics**: Add the topic where the response will be sent; in this example `ai.flowx.updates.document.html.persist.v1` and its key: `uploadedDocument`.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_document_node_config.png)
    </Frame>

    #### Actions

    Configure the following node actions:

    * Upload File action with two child actions:
      * Business Rule
      * Send Data to User Interface
    * Save Data action

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_document_actions.png)
    </Frame>

    #### Upload file action

    This is a standard predefined FlowX Node Action for uploading files. This is done through Kafka and by using `persist` topics.

    <Accordion title="Configuring the File Upload action">
      #### Action edit

      * **Action Type**: Set to **Upload File**.
      * **Trigger Type**: Choose **Manual** to allow user-triggered action.
      * **Required Type**: Set it as **Optional**.
      * **Repeatable**: Check this option if the action can be triggered multiple times.

      #### Parameters

      * **Topics**: Kafka topic where the file will be posted, in this example `ai.flowx.in.document.persist.v1`.

      <Tip>
        To identify your defined topics in your current environment, follow the next steps:

        * From the FLOWX.AI main screen, navigate to the **Platform Status** menu at the bottom of the left sidebar.
        * In the FLOWX Components list, scroll to the **document-plugin-mngt** line and press the eye icon on the right side.
        * In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → document → persist**. Here will find the in and out topics for persisting (uploading documents).

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_topics_persist.png)
        </Frame>
      </Tip>

      * **Document Type**: Metadata for the document plugin, in this example `BULK`.
      * **Folder**: Configure a value by which the file will be identified, in this example it will be the`${processInstanceId}` (it will be replaced at runtime with a generated process instance id).
      * **Advanced configuration (Show headers)**: This represents a JSON value that will be sent on the headers of the Kafka message, in this example:

      ```json theme={"system"}
      {"processInstanceId": ${processInstanceId}, "destinationId": "upload_document", "callbacksForAction": "uploadDocument"}`
      ```

      <Tip>
        `callbacksForAction` - the value of this key is a string that specifies a callback action associated with the "upload\_document" destination ID (node). This is part of an event-driven system (Kafka send action) where this callback will be called once the "upload\_document" action is completed.
      </Tip>

      #### Data to send

      * **Keys**: Used when data is sent from the frontend via an action for data validation.
    </Accordion>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_config_a.png)
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_config_b.png)
    </Frame>

    <Info>
      When configuring the event handler that corresponds to the Upload File node action, you must set the **Action Type** to **Upload**. This ensures proper integration between the frontend interface and the backend upload functionality.

      <Frame>
        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_action_upload.png)
      </Frame>
    </Info>

    Now, configure the child actions of Upload File Action.

    #### Business rule

    This is necessary to create the path to display the uploaded document.

    <Accordion title="Configuring the Business Rule action">
      **Action Edit**

      * **Order**: Set to **1** so it will be processed before the second child action.
      * **Action Type**: Set to **Upload File**.
      * **Trigger Type**: Choose **Automatic**, it does not need user intervention.
      * **Required Type**: Set as **Mandatory**.
      * **Repeatable**: Check this option if the action can be triggered multiple times.

      **Parameters**

      * **Language**: In this example we will use **MVEL**.
      * **Body Message**: Fill in the body of the message request by applying a logic similar to the one utilized in configuring the "preview\_document" node. Establish a path that will be later employed to showcase the uploaded document within a preview UI component.

      ```js theme={"system"}
      adminPath = "https://admin-main.playground.flowxai.dev/document/";
      downloadPath = input.?uploadedDocument.?downloadPath;

      if(downloadPath != null){
          output.put("uploadedDocument", {
              "filePath" : adminPath + downloadPath
          });
      }
      ```
    </Accordion>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_business_rule_a.png)
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_business_rule_b.png)
    </Frame>

    #### Send Data to User Interface

    This is necessary to send the previously created information to the frontend.

    <Accordion title="Configuring the Send Data to User Interface action">
      **Action Edit**

      * **Order**: Set to **2** so it will be processed after the previously created Business Rule.
      * **Action Type**: Set to **Send data to user interface**.
      * **Trigger Type**: Choose **Automatic**, it does not need user intervention.
      * **Required Type**: Set as **Mandatory**.
      * **Repeatable**: Check this option if the action can be triggered multiple times.

      **Parameters**

      * **Message Type**: Set to **Default**.
      * **Body Message**: Populate the body of the message request; this object will be utilized to bind it to the File Preview UI element.

      ```json theme={"system"}
      {
          "uploadedDocument": {
              "filePath": "${uploadedDocument.filePath}"
          }
      }
      ```

      * **Target Process**: Used to specify to what running process instance should this message be sent - set to **Active Process**.
    </Accordion>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/send_to_UI_a.png)
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/send_to_UI_b.png)
    </Frame>

    #### Save Data

    Configure the last node action to save all the data.

    **Action edit**

    * **Order**: Set to **3**.
    * **Action Type**: Set to **Save Data**.
    * **Trigger Type**: Choose **Manual** to allow user-triggered action.
    * **Required Type**: Set as **Mandatory**.

    #### Request message example

    To initiate the document processing, a Kafka request with the following JSON payload will be sent through `..in` topic:

    <Info>
      This an example of a message that follows the custom integration data model.
    </Info>

    ```json theme={"system"}
    {
      "tempFileId": "05081172-1f95-4ece-b2dd-1718936710f7", //a unique identifier for the temporary file
      "customId": "119246", //a custom identifier associated with the document
      "documentType": "BULK" //the type of the document 
    }
    ```

    #### Response message example

    Upon successful processing, you will receive a JSON response on the `..out` topic with details about the processed document:

    ```json theme={"system"}
    {
      "customId": "119246",
      "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
      "documentType": "BULK",
      "documentLabel": null,
      "minioPath": "flowx-dev-process-id-119246/119246/458_BULK.pdf",
      "downloadPath": "internal/files/96975e03-7fba-4a03-99b0-3b30c449dfe7/download",
      "noOfPages": null,
      "error": null
    }
    ```

    Now the screen is configured for uploading the signed document:

    ![Upload File](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_document_signed.gif)
  </Step>
</Steps>

***

## Uploading multiple files

For the backend action configuration, see the [Upload File action](../../../../building-blocks/actions/upload-file-action) documentation.

***

## Receiving the reply

The response, containing information about the generated and uploaded documents as mentioned earlier, is sent to the output Kafka topic defined in the Kafka Receive Event Node. The response includes details such as file IDs, document types, and storage paths.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/final_response.png)
</Frame>

The reply body is expected to contain the following values:

* **customId**: A custom identifier associated with the document.
* **fileId**: The ID of the file.
* **documentType**: The document type.
* **minioPath**: The path where the uploaded file is saved. It represents the location of the file in the storage system, whether it's a MinIO path or an S3 path, depending on the specific storage solution.
* **downloadPath**: The download path for the uploaded file. It specifies the location from where the file can be downloaded.
* **noOfPages**: The number of pages in the document (if applicable).
* **filePath**: The path to the file that we built in our example so we can display the document.


# Enumerations
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations

Enumerations allow you to manage a collection of predefined values that can be used within UI components or templates. These values can be tailored for specific source systems or languages.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2012.36.20.png)
</Frame>

## Overview

Enumerations help you standardize and manage lists of values that are displayed in your applications. Each enumeration consists of one or more values with both an internal identifier (the code) and display strings (labels) for different languages. You can also establish hierarchies by creating child collections—for example, defining states within a country.

<Info>
  Enumerations are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific enumeration, right-click it and select **View History**.
</Info>

## User interface overview

The **Enumerations** tab is divided into the following sections:

### Header

* **New Enumeration** - Click this button to create a new enumeration.
* **Contextual Menu (three dots)** - Provides options for **Import** and **Export**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2012.53.55.png)
</Frame>

### Main table

* **Name** - Displays the name of each enumeration.
* **Edited At** - Indicates the last update timestamp for each enumeration.
* **View Details** - Allows you to update the enumeration name.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2012.42.36.png)
</Frame>

***

## Enumeration entry details

When you open an enumeration entry, define the following properties:

1. **Code** - Not displayed in the end-user interface, but used to assure value uniqueness
2. **Labels** - These are the display strings shown to end users in various languages.
3. **External source systems codes** - Specifies the corresponding codes for each external system that consumes the data. Connectors use these codes for data validation.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2013.14.01.png)
</Frame>

### Adding a new enumeration

To create a new enumeration:

1. **Open your project:**  Launch **FlowX Designer** and open your project.
2. **Access Enumerations:** Select **Enumerations** from the **CMS** tab.
3. **Name the Enumeration:** Enter a suggestive name and click **Add**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/create_new_enum.png)
</Frame>

### Configuring an enumeration

After creating an enumeration, add values to it by configuring:

* **Code:** A unique identifier (not visible to end-users).
* **Labels:** The display string for each language.
* **Source Systems:** The code values assigned for each external system consuming the data.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/enum_add_value.png)
</Frame>

<Info>
  You can find the list of available source systems under **Projects → Integrations → Systems**.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/systems.png)
  </Frame>
</Info>

### Creating a child collection

Enumerations can be organized hierarchically by defining child values for each entry. For example, you might define states as children under a country enumeration. Hierarchical structures enable cascading selections in the user interface; for instance, choosing a country in one dropdown can filter the states available in another.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/child_enum.png)
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/child_enum_example.png)
</Frame>

### Importing/exporting an enumeration

You can import or export enumerations using the following formats:

* **ZIP**
* **CSV**

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/export_import_enums.png)
</Frame>

<Warning>
  Every enumeration (root or child) must contain at least one **content value** (i.e., at least one label is provided) before attempting an import or export. Remember, the term *value* here refers to the display content for end-users, not the internal code.
</Warning>

### Enumerations example

Consider an example for **Activity Domain Companies**. You can use hierarchies to organize related domains and activities.

#### **Activity Domain Companies → Agriculture forestry and fishing:**

* **Agriculture, hunting, and related services →**

<details>
  <summary>Cultivation of non-perennial plants:</summary>

  * Cultivation of cereals (excluding rice), leguminous plants and oilseeds
  * Cultivation of rice
  * Growing of vegetables and melons, roots and tubers
  * Cultivation of tobacco
</details>

<details>
  <summary>Cultivation of plants from permanent crops:</summary>

  * Cultivation of grapes
  * Cultivation of grapes
  * Cultivation of seeds and stone fruits
  * Cultivation of oil seeds
</details>

<details>
  <summary>Animal husbandry:</summary>

  * Raising of dairy cattle
  * Raising of other cattle
  * Raising horses and other horses
</details>

* **Forestry and logging →**

<details>
  <summary>Forestry and other forestry activities:</summary>

  * Forestry and other forestry activities
</details>

<details>
  <summary>Logging:</summary>

  * Logging
</details>

<details>
  <summary>Collection of non-wood forest products from spontaneous flora:</summary>

  * Collection of non-wood forest products from spontaneous flor
</details>

* **Fisheries and aquaculture →**

<details>
  <summary>Fishing:</summary>

  * Sea fishing
  * Freshwater fishing
</details>

<details>
  <summary>Aquaculture:</summary>

  * Maritime aquaculture
  * Freshwater aquaculture
</details>

This is the output after adding all the lists/collections from above:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/enumerations_output.gif)
</Frame>

***

## Displaying enum labels in text components

Text components can display the human-readable **label** of an enumeration value instead of the raw code. When a data key bound to a text component references an enumeration field, the renderer automatically resolves the stored code to its corresponding label at display time.

For example, if a Select component stores the code `RO` from a "Countries" enumeration, a text component bound to the same data key displays **Romania** (the label) rather than `RO`.

Enumeration values are **prefetched** from the data model before action resolution, so label lookups happen without additional network requests at render time.


# Media library
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/media-library

Centralized hub for managing PDFs, images, GIFs, and other media files uploaded to processes.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml4.png)
</Frame>

<Tip>
  You can also upload an image directly to the Media Library on the spot when configuring a process using the [**UI Designer**](../../../building-blocks/ui-designer/ui-designer). For more information, see the [**Image component documentation**](../../../building-blocks/ui-designer/ui-component-types/image).
</Tip>

<Info>
  Media assets are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific asset, right-click it and select **View History**.
</Info>

## Uploading a new asset

To upload an asset to the Media Library, follow the next steps:

1. Open **FlowX Designer**.
2. Go to **Content Management** tab and select **Media Library**.
3. Click **Add new item** ("+" button in the top-right corner), the following details will be displayed:
   * **Upload item** - opens a local file browser
   * **Key** - the key must be unique, you cannot change it afterwards

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml7.png)
</Frame>

4. Click **Upload item** button and select a file from your local browser.
5. Click **Add** to upload the asset.

<Info>
  You can upload files in **PNG, JPEG, JPG, GIF, SVG, WebP, or PDF** format. The maximum supported file size is **25 MB** for any file type.
</Info>

## Displaying assets

You can preview all the uploaded assets by accessing the **Media Library**.

You have the following information about assets:

* Preview (thumbnail 48x48)
* Key
* Format ("-" for unknown format)
* Size
* Used as icon
* Edited at
* Edited by

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml5.png)
</Frame>

## Searching assets

You can search an asset by using its key (full or substring).

## Updating assets

You can replace an item on a specific key (this will not break references to process definitions). To do that, click on the asset and select \**Upload item* then click **Update**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml6.png)
</Frame>

## Icons

The Icons feature allows you to personalize the icons used in UI elements. By uploading SVG files through the Media Library and marking them, you can choose icons from the available list in the UI Designer.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml2.png)
</Frame>

* **Use as icon** - this will mark the SVG file as an icon and it will be displayed in the UI Designer

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml1.png)
</Frame>

<Info>
  When selecting icons in the UI Designer, only SVG files marked as icons in the Media Library will be displayed.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml3.png)
  </Frame>
</Info>

<Info>
  To ensure optimal visual rendering and alignment within your UI elements, it is recommended to use icons with small sizes such as: 16px, 24px, 32px.

  Using icons specifically designed for these sizes helps maintain consistency and ensures a visually pleasing user interface. It is advisable to select icons from icon sets that provide these size options or to resize icons proportionally to fit within these dimensions.

  <Warning>
    Icons are displayed or rendered at their original, inherent size.
  </Warning>
</Info>

## Referencing assets in UI Designer

You have the following options when configuring image components using [UI Designer](../../../building-blocks/ui-designer/ui-designer):

* **Source Location** - here you must select **Media Library** as source location (or directly select "Upload to Media Library" button for on the spot upload)
* **Image Key**  - automatically populated with the key of the asset when selecting an asset from the Media Library

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml8.png)
</Frame>

<Tip>
  For more details on how to configure an image component, see the [**Image component documentation**](../../../building-blocks/ui-designer/ui-component-types/image).
</Tip>

## Customization

Content-specific icons pertain to the content of UI elements, such as icons for [input fields](../../../building-blocks/ui-designer/ui-component-types/form-elements/input-form-field) or [send message buttons](../../../building-blocks/ui-designer/ui-component-types/buttons). These icons are readily accessible in the [UI Designer](../../../building-blocks/ui-designer/).

<Frame>
  ![Adding icons to UI elements](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/icon_add_ui.gif)
</Frame>

More details on how to add icons on each element, check the sections below:

<CardGroup>
  <Card title="Input element" href="../../../building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-styling" icon="file" />

  <Card title="Select element" href="../../../building-blocks/ui-designer/ui-component-types/form-elements/select-form-field#icons" icon="file" />

  <Card title="Buttons" href="../../../building-blocks/ui-designer/ui-component-types/buttons#icons" icon="file" />
</CardGroup>

## Export and import media assets

You can export and import media assets to transfer them between projects or environments.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml9.png)
</Frame>

### Exporting

To export media assets:

1. Open the context menu on the Media Library list page
2. Select **Export**
3. All media assets in your project are downloaded as a ZIP file

### Importing

To import media assets:

1. Open the context menu on the Media Library list page
2. Select **Import**
3. Select the ZIP file exported from another project or environment
4. If assets with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting asset (or use **Apply to all**):
   * **Keep both** - imports the asset as a new copy alongside the existing one
   * **Replace** - overwrites the existing asset with the imported version
   * **Skip this one** - keeps the existing asset unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>


# Forwarding notifications
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/forwarding-notifications-to-an-external-system

If the Notification service is not directly connected to an SMTP / SMS server and you want to use an external system for sending the notifications, you can use the notification plugin just to forward the notifications to your custom implementation.

### Check needed Kafka topics

Yu will need the name of the kafka topics defined at the following environment variables:

* `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` - topic used to trigger the request to send a notification
* `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` - the notification will be forwarded on this topic to be handled by an external system
* `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` - topic used for sending replies after sending the notification

<Tip>
  You can check the defined topics by going to **FlowX Designer > Platform Status > notification-plugin-mngt > kafkaTopicsHealthCheckIndicator > details > configuration > topic > notification**.
</Tip>

### Example: send a notification from a business flow

Let's pick a simple use case. Imagine we need to send a new welcome letter when we onboard a new customer. You must follow the next steps:

1. Configure the [template](./managing-notification-templates) that you want to use for the welcome email, use the [WYSIWYG Editor](../../wysiwyg)

<Check>
  Make sure that the **Forward on Kafka** checkbox is ticked, so the notification will be forwarded to an external adapter.
</Check>

2. Configure the data model for the template.

3. To configure a document template, first, you need to define some information stored in the [Body](../../wysiwyg#notification-templates):

* **Type** - MAIL (for email notifications)
* ❗️**Forward on Kafka** - if this box is checked, the notification is not being sent directly by the plugin to the destination, but forwarded to another adapter
* **Language** - choose the language for your notification template
* **Subject** - enter a subject

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notification_email.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/data_model_notif.png)

4. Use the FlowX Designer to create a process definition.
5. Add a [**Send Message Task**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-send-task-node) and a [**Receive Message Task**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-message-receive-task-node) (one to send the request, one to receive the reply).
6. Check if the needed topic (defined at the following environment variable) is configured correctly: `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN`.
7. Add the proper configuration to the action, the Kafka topic, and the body message.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notif_params_send.png)
</Frame>

<Info>
  **Forward on Kafka** option will forward the notification to an external adapter, make sure the needed Kafka topic for forwarding is defined/overwritten using the following environment variable: `KAFKA_TOPIC_EXTERNAL_OUT`.
</Info>

7. Run the process and look for the response (you can view it via the **Audit log**) or by checking the responses on the Kafka topic

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notif_send_resp.png)
</Frame>

Response example at `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT`:

```json theme={"system"}
{
  "templateName": "welcomeLetter",
  "receivers": [
    "john.doe@mail.com"
  ],
  "channel": "MAIL",
  "language": "en"
}

```


# Managing notification templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates

You can create and manage notification templates using FlowX.AI Designer by accessing the dedicated section.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templates.png)
</Frame>

### Configuring a template

To configure a notification template, first, you need to select some information stored in the **Body**:

1. **Type** - could be either MAIL or SMS notifications
2. **Email Server** - select the email delivery method (available for MAIL type):
   * **Predefined Email Connection** (default) - send emails directly through a configured SMTP server using the [Send Notification](../../../../building-blocks/actions/send-notification-action) action
   * **Forward on Kafka** - forward the notification to Kafka for the Notifications Plugin or an [external adapter](./forwarding-notifications-to-an-external-system) to handle (this is mandatory for SMS notification templates)
3. **Email Sender** - displayed only when **Email Server** is set to **Predefined Email Connection**:
   * **Default Server** (default) - uses the default SMTP connection configured at the environment level
   * Or select a specific [Email Sender](../../../integrations/email-sender) data source configured in Integration Designer
4. **Language** - choose the language for your notification template
5. **Subject** - enter a subject

<Info>
  You can edit the content for each language you have defined in the project.
</Info>

<Frame>
  ![Notification template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templ_ex.png)
</Frame>

#### Editing the content

You can edit the content of a notification template by using the [WYSIWYG](../../wysiwyg) editor embedded in the body of the notification templates body.

### Configuring the data model

Using the **Data model** tab, you can define key pair values (parameters) that will be displayed and reused in the editor. Multiple parameters can be added:

* STRING
* NUMBER
* BOOLEAN
* OBJECT
* OBJECT\_REF
* ARRAY
* ARRAY\_REF
* ENUM

<Frame>
  ![Data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_template_dm.png)
</Frame>

After you defined some parameters in the **Data Model** tab, you can type "**#**" in the editor to trigger a dropdown where you can choose which one you want to use/reuse.

<Frame>
  ![Data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templ_dm.gif)
</Frame>

<Card title="WYSIWYG Editor" href="/docs/platform-deep-dive/wysiwyg" icon="pencil" />

### Testing the template

You can use the test function to ensure that your template configuration is working as it should before publishing it.

<Frame>
  <video />
</Frame>

The test modal includes the following fields:

* **Receivers emails** — recipient email addresses for the test
* **Language** — select the template language to test
* **Attachments** — upload files to test attachment handling
* **Template data** — provide values for template variables
* **Advanced** (hidden section) — **Sender Name** and **Sender Email** overrides

<Warning>
  If some keys (marked as mandatory) are not used in the template, the test will not go through.
</Warning>

### Other actions

When opening the contextual menu (accessible by clicking on the breadcrumbs button), you have multiple actions to work with the notifications templates:

* **Configure** - edit the template
* **Export template** - export a template as a ZIP file
* **Audit log** - view the audit log
* **Copy to another project/library** - copy a template to another project/library
* **Duplicate** - duplicate a template
* **Delete** - delete a template

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templ_menu.png)
</Frame>

***

### Export and import

You can export and import notification templates to transfer them between projects or environments (for example, from development to UAT to production).

#### Exporting a template

To export a notification template:

1. Open the contextual menu (breadcrumbs button) for the template you want to export
2. Select **Export template**
3. The template is downloaded as a ZIP file

#### Importing templates

To import notification templates:

1. Navigate to the **Notification Templates** list
2. Open the context menu and select **Import from ZIP**
3. Select the ZIP file exported from another project or environment
4. If templates with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting template (or use **Apply to all**):
   * **Keep both** - imports the template as a new copy alongside the existing one
   * **Replace** - overwrites the existing template with the imported version
   * **Skip this one** - keeps the existing template unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>


# Notification Templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview

You can add Notification Templates to your custom FlowX.AI deployment. The plugin will **enhance the core platform capabilities with functionality specific to sending various notifications**.

The Notification Templates feature offers the following features:

* Email notifications
* SMS templates to mobile devices

<Info>
  To use the Notification Templates feature to send notifications, via SMS channel, a third party provider for SMS communication is needed, for example, [Twilio](https://www.twilio.com/).
</Info>

* Forward custom notifications to external outgoing services
* Generate and validate OTP passwords for user identity verification

You can also use the Notification Templates feature to track what notifications have been sent and to whom.

Let's go through the steps needed to deploy and set up the Notification Templates feature:

## Using Notification Templates

After deploying the Notification Templates feature in your infrastructure, you can start sending notifications by configuring related actions in your **process definitions**.

Before adding the corresponding **actions** in your process definition, you will need to follow a few steps:

* make sure all prerequisites are prepared, for example, the [notification templates](./managing-notification-templates) you want to use
* the database is configured properly
* for each **Kafka** event type, you will need two Kafka topics:
  * one for the request sent from the FlowX Engine to the Notification Templates feature
  * one for the corresponding reply

<Card title="Kafka configuration for Notifications plugin" href="../../../../../setup-guides/notifications-plugin-setup#kafka-configuration" icon="gears">
  **DEVELOPER**
</Card>

<Info>
  The topic names configured for the plugin should match the ones used when configuring the engine and when adding plugin-related process actions:

  * FlowX Engine is listening for messages on topics with names of a certain pattern, make sure to use an outgoing topic name that matches the pattern configured in the Engine

  For more information, see the [Kafka configuration guide](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka).

  * to make a request to the plugin, the process definition needs to have an action of type `Kafka send` that has an action parameter with key `topicName` and the needed topic name as a value
  * to receive a reply from the plugin, the process definition needs to have a receiving node with a node value with key `topicName` and the topic name as the value
</Info>

After all the setup is in place, you can start adding custom actions to the processes.

Let's go through a few examples. These examples cover both the configuration part, and the integration with the engine for all the use cases.

<CardGroup>
  <Card title="Managing notification templates" href="managing-notification-templates" />

  <Card title="Send a notification" href="sending-a-notification" />

  <Card title="Send an email with attachements" href="sending-an-email-with-attachments" />

  <Card title="Forward notifications to an external system" href="forwarding-notifications-to-an-external-system" />

  <Card title="OTP flow" href="otp-flow" />
</CardGroup>


# Generate OTP
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/generate-otp

There are some cases when you will need to generate an OTP (One Time Password) from a business flow, for example when validating an email account.

The notifications plugin handles both the actual OTP code generation and sending the code to the user using a defined [notification template](../managing-notification-templates).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/otp_archi.png)

## Define needed Kafka topics

<Info>
  **DEVELOPER**: Kafka topic names can be set/found by using the following environment variables in your Notifications plugin deployment:

  * `KAFKA_TOPIC_OTP_GENERATE_IN` — the OTP generate request is sent on this topic. **Default:** `ai.flowx.plugin.notification.trigger.generate.otp.v1`
  * `KAFKA_TOPIC_OTP_GENERATE_OUT` — after the OTP is generated and sent to the user, the response is sent back to the Engine on this topic. **Default:** `ai.flowx.engine.receive.plugin.notification.generate.otp.results.v1`
</Info>

<Info>
  The Engine is listening for messages on topics with names of a certain pattern, make sure to use an outgoing topic name that matches the pattern configured in the Engine.
</Info>

## Request to generate an OTP

Send the request on the `KAFKA_TOPIC_OTP_GENERATE_IN` topic. The body holds the following values:

| Field               | Description                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `processInstanceId` | Process instance ID                                                                           |
| `templateName`      | Name of the [notification template](../managing-notification-templates) used to send the code |
| `language`          | Template language to use, for example `en`                                                    |
| `channel`           | Notification channel: `MAIL`, `SMS`, or `PUSH`                                                |
| `clientId`          | Business identifier of the client (for example, the SSN)                                      |
| `recipient`         | Notification receiver: email address or phone number                                          |
| `data`              | Parameters substituted into the notification template (for example, `name`)                   |

```json theme={"system"}
{
  "processInstanceId": 1994,
  "templateName": "your_otp_mail_template",
  "language": "en",
  "channel": "MAIL",
  "clientId": "1871201460101",
  "recipient": "john.doe@example.com",
  "data": {
    "name": "John"
  }
}
```

<Info>
  You don't send the OTP code yourself. The plugin generates it and automatically injects it into the template data under the reserved key **`otpValue`** before rendering — see [Notification template](#notification-template) below.
</Info>

<Warning>
  The `contentParams` field is deprecated. Use `data` instead.
</Warning>

## Notification template

The OTP code is delivered using a notification template created in **Content Management** → **Notification Templates**. In the template **Body**, reference the generated code with the `#otpValue` placeholder (this maps to `${otpValue}` in the **Source** view):

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otpTemplate_example_notif_template.png)
</Frame>

In the template **Data model**, declare the parameters the template expects. `otpValue` holds the generated code; any other parameters (such as `name`) are taken from the `data` object in the request:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otpTemplate_example_notif_data_model-template.png)
</Frame>

<Tip>
  You never pass `otpValue` in the request — the plugin adds it automatically. The number of digits in the code is controlled by the `FLOWX_OTP_LENGTH` environment variable (**default:** `4`).
</Tip>

## Response from generate OTP

The response is sent back to the Engine on the `KAFKA_TOPIC_OTP_GENERATE_OUT` topic. The reply body holds the following values:

| Field               | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `processInstanceId` | Process instance ID                                               |
| `clientId`          | Client identifier                                                 |
| `channel`           | Notification channel used                                         |
| `otpSent`           | Confirmation whether the notification was sent: `true` or `false` |
| `error`             | Error description, if any (otherwise `null`)                      |

```json theme={"system"}
{
  "processInstanceId": 1994,
  "clientId": "1871201460101",
  "channel": "MAIL",
  "otpSent": true,
  "error": null
}
```

## Example: generate an OTP from a business flow

This example uses a simple process with a **Kafka send** node (to request the OTP) and a **Kafka receive** node (to capture the response):

Identify the business identifier you will use to validate the OTP (for example, a user identification number).

1. Configure the notification template that you want to use (for example, a `MAIL` template).
2. Make sure the Kafka communication through the `KAFKA_TOPIC_OTP_GENERATE_IN` topic (send the OTP request) and the topic used to receive the response (`KAFKA_TOPIC_OTP_GENERATE_OUT`) is defined properly.

<Tip>
  You can check the defined topics by going to **FlowX Designer** → **Platform Status** → **notification-plugin-mngt** → **kafkaTopicsHealthCheckIndicator** → **details** → **configuration** → **topic** → **otp**.
</Tip>

3. Add a **Kafka send** action to the correct node in the process definition. Set the topic to `KAFKA_TOPIC_OTP_GENERATE_IN` and configure the message body:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otp_generate_kafka_action_config.png)
</Frame>

4. Add a **Kafka receive** node and configure the process key where the response is stored (for example, `otpResult`).

5. When the process runs, the response lands on that key, confirming the OTP was sent:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otp_response_example_on_kafka.png)
</Frame>

6. The recipient receives the OTP code rendered from the notification template:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/email_received_example.png)
</Frame>


# Handling OTP
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/otp-flow

The notifications plugin can also be used for handling the one time password (OTP) generation and validation flow.

The flow is made of two steps, the OTP generation and the OTP validation.

### OTP Configuration

The desired character size and expiration time of the generated one-time-passwords can also be configured using the following environment variables:

* `FLOWX_OTP_LENGTH` — number of digits in the generated code. **Default:** `4`
* `FLOWX_OTP_EXPIRETIMEINSECONDS` — how long the OTP stays valid, in seconds. **Default:** `6000`

Let's go through the examples for both steps:

<Card title="Generate OTP" href="generate-otp" icon="link" />

<Card title="Validate OTP" href="validate-otp" icon="link" />


# Validate OTP
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/validate-otp

Validate one-time passwords (OTP) sent via SMS or email using the Notifications Plugin Kafka integration.

## Define needed Kafka topics

Kafka topic names can be set by using environment variables:

* `KAFKA_TOPIC_OTP_VALIDATE_IN` - the event sent on this topic (with an OTP and an identifier) will check if the OTP is valid
* `KAFKA_TOPIC_OTP_VALIDATE_OUT` - the response for this request will validate an OTP, the reply is sent back to the Engine on this topic

<Tip>
  You can check the defined topics by going to **FlowX Designer > Platform Status > notification-plugin-mngt > kafkaTopicsHealthCheckIndicator > details > configuration > topic > otp**.
</Tip>

<Info>
  The Engine is listening for messages on topics with names of a certain pattern, make sure to use an outgoing topic name that matches the pattern configured in the Engine.
</Info>

## Request to validate an OTP

Values expected in the request body:

* **processInstanceId** = process instance ID
* **client id** = the user unique ID in the system
* **channel** = notification channel: SMS/MAIL
* **otp** = OTP code that you received, used to compare with the one that was sent from the system

Example:

```json theme={"system"}
{ 
    "processInstanceId": 12345, 
    "clientId": "1871201460101", 
    "channel": "MAIL", 
    "otp": "1111" 
}
```

### Reply from validate OTP

The response is sent back to the Engine on the `KAFKA_TOPIC_OTP_VALIDATE_OUT` topic. The reply body holds the following values:

| Field               | Description                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `processInstanceId` | Process instance ID                                                                                |
| `clientId`          | The user unique ID in the system                                                                   |
| `channel`           | Notification channel used                                                                          |
| `otpValid`          | Confirmation whether the provided OTP code matched the one sent from the system: `true` or `false` |

```json theme={"system"}
{
  "processInstanceId": 12345,
  "clientId": "1871201460101",
  "channel": "MAIL",
  "otpValid": true
}
```

## Example: validate an OTP from a business flow

Similar to the generation of the OTP you can validate the OTP that was generated for an identifier.

1. Check that the needed topics are configured correctly: (`KAFKA_TOPIC_OTP_VALIDATE_IN` and `KAFKA_TOPIC_OTP_VALIDATE_OUT`)
2. Add the actions for sending the request to validate the OTP on the node that contains the 'Generate OTP' actions
3. Add the proper configuration to the action, the Kafka topic and configure the body message.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/validate_otp_temp.png)
</Frame>

4. Add a node to the process definition (for the [Receive Message Task](../../../../../building-blocks/node/message-send-received-task-node#receive-message-task))
5. Configure on what key you want to receive the response on the process instance parameters

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/validate_otp3.png)
</Frame>


# Sending a notification
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification

Learn how to configure and implement notification functionality in your business processes using the FlowX.AI Notifications Plugin.

The FlowX.AI Notifications Plugin enables you to send various types of notifications such as emails and SMS messages. This document explains how to integrate notification functionality into your business processes.

## Configuring the notification process

To configure a business process that sends notifications, follow these steps:

1. Create or edit a [notification template](./managing-notification-templates) in **FlowX Designer**
2. Design your BPMN process in **Process Designer** with:
   * A [send message task](../../../../building-blocks/node/message-send-received-task-node#send-message-task)
   * A [receive message task](../../../../building-blocks/node/message-send-received-task-node#receive-message-task)
3. Configure required [node actions](../../../../building-blocks/actions/actions)
4. Set up the request body parameters

<Info>
  The notification process uses Send message task/receive message task nodes to manage communication between components.
</Info>

The diagram below shows how the notification system integrates with your business processes:

<Frame>
  <img alt="Notification architecture diagram" />
</Frame>

<Check>
  **DEVELOPER NOTE**: Ensure that Kafka topics are properly configured in your environment by setting these variables:

  * `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` (default: `ai.flowx.plugin.notification.trigger.send.notification.v1`) - Topic for notification requests
  * `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` (default: `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1`) - Topic for notification responses
</Check>

## Send notification request body parameters

Your notification request must include these parameters:

|      Key      |                             Definition                            |           |
| :-----------: | :---------------------------------------------------------------: | :-------: |
|  templateName |            The name of the notification template to use           | Mandatory |
|    channel    |                   Notification channel: SMS/MAIL                  | Mandatory |
|   receivers   |     Notification recipients: email addresses or phone numbers     | Mandatory |
|  ccReceivers  |            Notification CC recipients: email addresses            |  Optional |
|  bccReceivers |            Notification BCC recipients: email addresses           |  Optional |
|    language   |    The language code of the template to use (e.g., "en", "fr")    | Mandatory |
| contentParams |      Parameters for filling the template with dynamic content     |  Optional |
|  senderEmail  |              Email address of the notification sender             |  Optional |
|   senderName  |                  Name of the notification sender                  |  Optional |
|  attachments  | Files to attach to the notification (only for MAIL notifications) |  Optional |

### Using dynamic keys

Notifications support dynamic keys (placeholders) that allow for personalized content:

* Dynamic keys use the syntax `${...}` to insert data from the process context
* The system fetches corresponding values from the specified data path
* This approach eliminates hardcoding and supports personalized content
* Example: `${application.client.firstName}` retrieves and displays the client's first name

<CodeGroup>
  ```json Request Example with Dynamic Content theme={"system"}
  {
    "templateName": "ClientRelationshipEmailConfirmation",
    "channel": "MAIL",
    "receivers": [
      "${application.client.email}"
    ],
    "language": "en",
    "data": {
      "firstInputClient": "${application.client.firstName}"
    },
    "attachments": [
      {
        "path": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.minioPath}",
        "filename": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.documentType}.pdf"
      }
    ]
  }
  ```
</CodeGroup>

## Implementation example

Let's implement a welcome email notification for new customer onboarding.

<Steps>
  <Step title="Create a notification template">
    First, create and configure your welcome email template. See [Managing notification templates](./managing-notification-templates) for detailed instructions.

    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/welcomeLetter_template.gif)

    With notification templates, you can:

    * Set up subjects and body content with a WYSIWYG editor
    * Add dynamic fields using the data model to include recipient-specific information
    * Define multiple language versions of the same template
    * Configure notification types and delivery channels
  </Step>

  <Step title="Design the BPMN process">
    Inside your project, create a process definition with:

    * A [User Task](../../../../building-blocks/node/user-task-node) to capture the recipient's email address and other user inputs if needed
    * A [**Send Message Task**](../../../../building-blocks/node/message-send-received-task-node#send-message-task)
    * A [**Receive Message Task**](../../../../building-blocks/node/message-send-received-task-node#receive-message-task)

    This pattern enables asynchronous notification handling through Kafka messaging.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_notification_bpmn.png)
    </Frame>
  </Step>

  <Step title="Configure the send message task">
    On the send message task, add a Kafka send action with the following settings:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/kafka_send_action_notif.png)
    </Frame>

    * **Topics**:
      * Use the value from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` environment variable
      * Example (in our case): `flowx-notifications-devmain`

    <Tip>
      To find defined topics in your environment:

      1. Navigate to **FlowX Designer > Platform Status**
      2. Select **notification-plugin-mngt**
      3. Open **kafkaTopicsHealthCheckIndicator > details > configuration > topic > notifications**

      <Frame>
        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notification_internal_in_topi.png)
      </Frame>
    </Tip>

    * **Message** (expected parameters):
      * templateName (string)
      * channel (string)
      * language (string)
      * receivers (array) - usually extracted from process context but also can be a static value
    * **Can include**: `contentParams` (object) for dynamic content, `attachments` (array) for emails

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_send_parameters.png)
    </Frame>
  </Step>

  <Step title="Configure the receive message task">
    * On the receive message task, add a data stream topic where you will receive the confirmation that the notification was sent:
      * **Data stream topics**:
        * Use the value from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` environment variable
        * Example (in our case): `ai.flowx.updates.devmain.notification.request.v1`

    To add a data stream topic, follow the steps below:

    1. On your **Receive Message Task** node, click on the **Node Config** tab.
    2. Then under **Data stream topics** click **Add stream**.
    3. Select **Custom** and enter the topic name from the `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` environment variable.
    4. Add a key where you will see the response added to the process instance.
    5. Click **Save**.

    <Info>
      To find the corresponding data stream topic in your environment follow the same steps as in the [previous step](#configure-the-send-message-task)
    </Info>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/receive_notification_node.png)
    </Frame>
  </Step>

  <Step title="Run and verify the process">
    Execute the process and verify the results by:

    * Checking the audit log
    * Checking the process instance status
    * Monitoring responses on the `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` topic

    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notification_sent.png)

    When successful, you'll receive a response on the `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` topic similar to this:

    <CodeGroup>
      ```json Response Example theme={"system"}
      {
        "identifier": null,
        "templateName": "welcomeLetter",
        "language": "en",
        "error": null
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Integration with document generation

You can enhance your notifications by attaching dynamically generated documents. To accomplish this:

Set up document templates using the Document Plugin
Generate documents in your process before sending the notification
Reference the generated documents in the notification request using dynamic keys:

```json theme={"system"}
"attachments": [  
  {
    "path": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.minioPath}",
    "filename": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.documentType}.pdf"
  }
]
```

This integration creates a complete communication flow where personalized documents are automatically generated and sent to recipients.

## Troubleshooting

<Accordion title="Missing Kafka topics">
  Ensure that all required Kafka topics are properly configured in your environment variables. Check the Platform Status screen for confirmation that topics are available and accessible.
</Accordion>

<Accordion title="Notification not received">
  Verify that the receiver information is correct and that your template is properly configured. Check the audit log for any error messages in the notification response.
</Accordion>

<Accordion title="Template rendering issues">
  If your notification is sent but doesn't display properly, check that all template variables are correctly defined and that the contentParams in your request match the expected template variables.
</Accordion>

<Accordion title="Dynamic key not resolving">
  If a dynamic key isn't displaying the expected value, verify the path is correct and that the data exists in the process context. Dynamic keys are case-sensitive and must match the exact path to the data.
</Accordion>

<Accordion title="Attachment problems">
  For issues with attachments, ensure the document was successfully generated and stored before attempting to attach it. Check that the path and filename are correctly specified in the attachment configuration.
</Accordion>


# Sending an email
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments

To use the notification plugin for sending emails with attachments, you must define the same topic configuration as for sending regular notifications. A notification template must be created, and the corresponding Kafka topics must be defined.

<Check>
  Before proceeding, make sure you understand [how to send basic notifications](./sending-a-notification).
</Check>

<Note>
  For **new processes**, use the [Send Notification action](../../../../building-blocks/actions/send-notification-action) instead. It provides typed configuration fields and validation, and runs through the same notification backend. This Kafka-based guide is preserved for existing flows and advanced cases where the payload must be hand-crafted.
</Note>

## Overview

This guide explains how to send emails with document attachments through the notification plugin. You'll learn how to:

* Configure email templates with dynamic content
* Reference generated documents as attachments
* Implement the complete email notification flow in your processes

## Prerequisites

1. A configured notification template (see [Managing notification templates](./managing-notification-templates))
2. Properly defined Kafka topics for the notification plugin
3. Files to attach (such as generated documents or uploaded files)

## Implementing email notifications with attachments

Let's walk through a common scenario: sending a customer a copy of their account details document via email.

<Frame>
  ![Email notification process flow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_an_email.png)
</Frame>

<Card title="Document Generation" href="../documents-plugin/generating-from-html-templates">
  If you need to generate the document first, see the document generation guide.
</Card>

### Understanding document references

When you generate a document, as explained in the [Generating documents](../documents-plugin/generating-from-html-templates) guide, you need to reference two key pieces of information:

1. **minioPath**: The storage location of the generated document
2. **documentType**: The type identifier used to create the attachment filename

These values are stored in the process instance with the following structure:

```
generatedDocuments.generatedFiles.{{customId}}.{{templateName}}.minioPath
generatedDocuments.generatedFiles.{{customId}}.{{templateName}}.documentType
```

For example, if your document generation used:

* customId: "ClientsFolder"
* templateName: "AccountCreation"

The paths would be:

```json theme={"system"}
...
  "attachments": [
    {
      "path": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.minioPath}",
      "filename": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.documentType}.pdf"
    }
  ]
```

<Check>
  You can verify these values in the process instance details:

  <Frame>
    ![Process instance details showing document paths](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/generate_doc_template_first.png)
  </Frame>
</Check>

### Step-by-step implementation

<Steps>
  <Step title="Prepare your email template (notification template)">
    Configure the template you'll use for the email:

    * Define subject line, body text, and placeholders for dynamic content
    * Set proper HTML formatting if needed
    * Test the template to ensure it displays correctly

    <Frame>
      ![Email template example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/email_template.png)
    </Frame>

    See [Managing notification templates](./managing-notification-templates) for detailed instructions.
  </Step>

  <Step title="Verify Kafka topic configuration">
    Confirm that the required Kafka topics are properly defined:

    1. Navigate to **FlowX Designer → Platform Status**
    2. Select **notification-plugin-mngt**
    3. Expand **kafkaTopicsHealthCheckIndicator → details → configuration → topic → notification → internal**
    4. Verify that the input and output topics for email notifications are listed

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_kafka_topics.png)
    </Frame>
  </Step>

  <Step title="Add a Send Message Task (Kafka) and Receive Message Task (Kafka)">
    In your process definition:

    1. Open the process definition in your project in FlowX Designer
    2. Add a [Send Message Task (Kafka)](../../../../building-blocks/node/message-send-received-task-node#send-message-task) after the document generation step
    3. Add a [Receive Message Task (Kafka)](../../../../building-blocks/node/message-send-received-task-node#receive-message-task) after the Send Message Task

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_an_email_bpmn.png)
    </Frame>
  </Step>

  <Step title="Configure the email request payload (Send Message Task)">
    On the Send Message Task, add a Kafka send action, add the corresponding Kafka topic and create the JSON payload containing all information needed for the email:

    ```json theme={"system"}
    {
      "templateName": "accountDetails",
      "channel": "MAIL",
      "receivers": ["something@email.com"],
      "language": "en",
      "contentParams": {
        "firsInput": "${application.client.firstName}",
        "secondInput": "${application.client.lastName}"
      },
      "attachments": [
        {
          "path": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.minioPath}",
          "filename": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.documentType}.pdf"
        }
      ]
    }
    ```

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_email_node.png)
    </Frame>

    Key parameters:

    * **templateName**: The name of your configured email template
    * **language**: The language code matching your template's language version
    * **receivers**: Array of email addresses (can use process data variables)
    * **ccReceivers**: Array of email addresses to be added as CC (can use process data variables)
    * **bccReceivers**: Array of email addresses to be added as BCC (can use process data variables)
    * **contentParams**: Values to replace template placeholders
    * **attachments**: Array of files to attach, with filename and minioPath/storage path
  </Step>

  <Step title="Configure the email success handler (Receive Message Task)">
    On the Receive Message Task, add a Kafka receive action, add the corresponding Kafka topic and configure the node with the following properties:

    * Go to **Node config** tab
    * Under **Data stream topics** select **Custom**
    * Add the topic name
    * Click **Save**

    <Frame>
      ![Kafka receive action configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-15%20at%2017.56.57.png)
    </Frame>
  </Step>

  <Step title="Run the process">
    Run the process and check the result in the process instance details:

    <Frame>
      ![Process instance details showing email success](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/result_send_email.png)
    </Frame>
  </Step>
</Steps>

## Request payload reference

### Required fields

| Field        | Description                                    | Example                                                  |
| ------------ | ---------------------------------------------- | -------------------------------------------------------- |
| templateName | The unique identifier of your email template   | "accountDetails"                                         |
| channel      | The delivery channel (use "MAIL" for email)    | "MAIL"                                                   |
| language     | Language code (must match a template language) | "en"                                                     |
| receivers    | List of email addresses to receive the message | \["[customer@example.com](mailto:customer@example.com)"] |

### Optional fields

| Field         | Description                                       | Example                 |
| ------------- | ------------------------------------------------- | ----------------------- |
| contentParams | Key-value pairs for template variable replacement | `{"firstName": "John"}` |
| attachments   | List of files to attach to the email              | See below               |

### Attachment structure

Each attachment requires:

```json theme={"system"}
{
  "path": "${path.to.file.in.storage}",
  "filename": "desired_filename.extension"
}
```

* **path**: References the storage location (usually a MinIO path from document generation)
* **filename**: The name recipients will see for the attached file (can include process variables)

## Testing and troubleshooting

After configuring your email notification:

1. Verify that variables resolve correctly in the template and attachment references
2. Check email delivery to test recipients
3. Review notification plugin logs if issues occur

### Common issues

| Problem             | Solution                                                                        |
| ------------------- | ------------------------------------------------------------------------------- |
| Email not received  | Verify template name, receiver address, and SMTP configuration                  |
| Missing attachment  | Check that the MinIO path is correct and the file exists                        |
| Template errors     | Ensure all variables in template have corresponding values in contentParams     |
| Variable resolution | Confirm process variables use the correct path (check in process instance view) |

For further assistance, check the notification plugin logs in your environment.


# Substitution tags
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/substitution-tags

Substitution tags are used to generate dynamic content across the platform. As **enumerations**, substitution tags can be defined for each language set for the solution.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/substitution_tags.png)
</Frame>

<Info>
  Substitution tags are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific substitution tag, right-click it and select **View History**.
</Info>

On the main screen inside **Substitution tags**, you have the following elements:

* **Key**
* **Values** - strings that are used in the end-user interface, according to the language set for the generated solution
* **Edit** - button used to edit substitution tags
* **Delete** - button used to delete substitution tags
* **New value** - button used to add a new substitution tag
* **Breadcrumbs menu** - access import, export, and other bulk actions
* **Search by** - search function used to easily look for a particular substitution tag

### Export and import

You can export and import substitution tags to transfer them between projects or environments.

#### Exporting

1. Open the breadcrumbs menu on the Substitution Tags list page
2. Select **Export** and choose the format:
   * **to JSON** - exports as a ZIP file containing JSON data
   * **to CSV** - exports as a CSV file

#### Importing

1. Open the breadcrumbs menu on the Substitution Tags list page
2. Select **Import** and choose the format:
   * **from ZIP** - import from a ZIP file exported from another environment
   * **from CSV** - import from a CSV file for bulk operations
3. Select the file to import
4. If substitution tags with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting tag (or use **Apply to all**):
   * **Keep both** - imports the tag as a new copy alongside the existing one
   * **Replace** - overwrites the existing tag with the imported version
   * **Skip this one** - keeps the existing tag unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

### Adding new substitution tags

To add a new substitution tag, follow the next steps.

1. Go to **FlowX Designer** and select the **Content Management** tab.
2. Select **Substitution tags** from the list.
3. Click **New value**.
4. Fill in the necessary details:
   * Key
   * Languages
5. Click **Add** after you finish.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/add_new_substitution.png)

<Info>
  When working with substitution tags or other elements that imply values from other languages defined in the CMS, when running a **process**, the default values extracted will be the ones marked by the default language.
</Info>

### Getting a substitution tag by key

```
public func getTag(withKey key: String) -> String?
```

All substitution tags will be retrieved by the [**SDK**](../../../../sdks/angular-renderer) before starting the first process and will be stored in memory.

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag using the method above, providing the key.

For example, substitution tags can be used to localize the content inside an application.

### Example

#### Localizing the app

<Info>
  You must first check and configure the FLOWX.AI Angular renderer to be able to replicate this example. For more information, see the [Angular renderer documentation](../../../../sdks/angular-renderer).
</Info>

The `flxLocalize` pipe is found in the `FlxLocalizationModule`.

```typescript theme={"system"}
import { FlxLocalizationModule } from 'flowx-process-renderer';
```

```typescript theme={"system"}
import { Component } from '@angular/core';

@Component({
  selector: 'app-dummy-component',
  template: ` <h3>{{ "stringToLocalize" | flxLocalize}}</h3>`,

})
export class DummyComponent{
 stringToLocalize: string = `@@localizedString`
}
```

Strings that need to be localized must have the '**@@**' prefix which the **flxLocalize** pipe uses to extract and replace the string with a value found in the substitution tags enumeration.

Substitution tags are retrieved when a start process call is first made, and it's cached on subsequent start process calls.

## Task Management localization

Substitution tags are essential for localizing Task Management interfaces. FlowX.AI provides **51 system substitution tags** (prefixed with `sys_tm_*`) specifically for Task Management localization:

* Table columns (title, stage, assignee, status, priority)
* Process states (created, started, finished, etc.)
* Task actions (assign, hold, unassign, execute)
* Bulk operations
* History events and comments
* User selection dialogs

<Card title="Task Management Localization" href="../task-management/task-management-localization" icon="language">
  Complete guide to localizing Task Management with all 51 substitution tags. Table grid localization is automatic.
</Card>


# FlowX.AI Scheduler
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/scheduler

The Scheduler is part of the core extensions of the FlowX.AI platform. You can add it to your custom FlowX deployment to enhance the core platform capabilities with functionality specific to scheduling messages.

The service offers the possibility to schedule a message that you only need to process after a configured time period.

It can be quickly deployed on the chosen infrastructure and then connected to the **FlowX.AI Engine** through Kafka events.

## Using the scheduler

After deploying the scheduler service in your infrastructure, you can start using it to schedule messages that you need to process at a later time.

One such example would be to use the scheduler service to expire processes that were started but haven't been finished.

<Warning>
  First you need to check the configured Kafka topics match the ones configured in the engine deployment.
</Warning>

<Check>
  For example the engine topics `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET` and `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP` **must** be the same with the ones configured in the scheduler at `KAFKA_TOPIC_SCHEDULE_IN_SET` and `KAFKA_TOPIC_SCHEDULE_IN_STOP` environment variables.
</Check>

When a process is scheduled to expire, the engine sends the following message to the scheduler service (on the topic `KAFKA_TOPIC_SCHEDULE_IN_SET`):

```json theme={"system"}
{
  "applicationName": "onboarding",
  "applicationId": "04f82408-ee66-4c68-8162-b693b06bba00",
  "payload": {
    "scheduledEventType": "EXPIRE_PROCESS",
    "processInstanceUuid": "04f82408-ee66-4c68-8162-b693b06bba00"
  },
  "scheduledTime": 1621412209.353327,
  "responseTopicName": "ai.flowx.process.expire.staging"
}
```

The scheduled time should be defined as `java.time.Instant`.

At the scheduled time, the payload will be sent back to the response topic defined in the message, like so:

```json theme={"system"}
{
  "scheduledEventType": "EXPIRE_PROCESS",
  "processInstanceUuid": "04f82408-ee66-4c68-8162-b693b06bba00"
}
```

If you don't need the scheduled message anymore, you can discard it by sending the following message (on the topic `KAFKA_TOPIC_SCHEDULE_IN_STOP`)

```json theme={"system"}
{
  "applicationName": "onboarding",
  "applicationId": "04f82408-ee66-4c68-8162-b693b06bba00"
}
```

These fields, `applicationName` and `applicationId` are used to uniquely identify a scheduled message.

<Card title="Scheduler setup" href="../../../setup-guides/scheduler-setup-guide" icon="gears">
  Steps to deploy and set up the service
</Card>


# FlowX.AI Data Search
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/search-data-service

Search for specific data across process instances using Elasticsearch-powered indexing for fast, precise results.

<Frame>
  ![Data Search Service Overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/data_search_ov.png)
</Frame>

The Data Search service enables you to find specific data across process instances within your FlowX.AI platform. It uses Elasticsearch to perform fast, indexed searches across process data.

<CardGroup>
  <Card title="Simple Search" icon="magnifying-glass" href="#simple-search">
    Search by a single field and value
  </Card>

  <Card title="Advanced Search" icon="filter" href="#advanced-search">
    Search using multiple criteria simultaneously
  </Card>

  <Card title="Array Search" icon="list" href="#array-search">
    Search within array elements and nested structures
  </Card>

  <Card title="Cross-Application" icon="globe" href="#cross-application">
    Search across multiple applications
  </Card>

  <Card title="Date Filtering" icon="calendar" href="#date-filtering">
    Filter results by process creation dates
  </Card>
</CardGroup>

## Prerequisites

Before using the Data Search service, ensure you have:

<AccordionGroup>
  <Accordion title="Elasticsearch Configuration">
    * Elasticsearch cluster running and accessible
    * Indexing enabled in FlowX Engine configuration
    * Proper network connectivity between services
  </Accordion>

  <Accordion title="Kafka Topics">
    * `KAFKA_TOPIC_DATA_SEARCH_IN` configured for requests
    * `KAFKA_TOPIC_DATA_SEARCH_OUT` configured for responses
    * Proper topic permissions and access
  </Accordion>

  <Accordion title="Process Data">
    * Process instances with indexed data
    * Searchable fields defined in Process Settings → Data Search
    * **"Update data search" flag enabled** on at least one node to trigger indexing
    * Completed process instances for reliable results
  </Accordion>
</AccordionGroup>

***

## Quick start

<Steps>
  <Step title="Set up your data process">
    Create a process that stores searchable data and configure field indexing.
  </Step>

  <Step title="Create a search process">
    Build a process with Kafka Send/Receive actions for search functionality.
  </Step>

  <Step title="Configure search parameters">
    Define your search criteria using simple, advanced, or array search syntax.
  </Step>

  <Step title="Handle search results">
    Process the returned data and display results to users.
  </Step>
</Steps>

### 1. Set up your data process

First, create a process that contains searchable data. Add a Service Task with a business rule:

<CodeGroup>
  ```json Example Client Data theme={"system"}
  output.put("application", {
    "client": {
      "personalInfo": {
        "firstName": "Sarah",
        "lastName": "Johnson", 
        "email": "sarah.johnson@techcorp.com",
        "phone": "+1-555-0101"
      },
      "address": {
        "country": "USA",
        "city": "San Francisco", 
        "state": "California",
        "zipCode": "94102"
      },
      "business": {
        "company": "TechCorp Inc",
        "industry": "Technology",
        "position": "CTO"
      },
      "account": {
        "type": "Premium",
        "status": "Active",
        "riskLevel": "Low"
      }
    }
  });
  ```

  ```json Example Client List Data theme={"system"}
  output.put("application", {
    "listClient": [
      {
        "firstName": "Maria",
        "lastName": "Rodriguez",
        "email": "maria.rodriguez@company.com",
        "department": "Engineering"
      },
      {
        "firstName": "John",
        "lastName": "Smith", 
        "email": "john.smith@company.com",
        "department": "Sales"
      },
      {
        "firstName": "Maria",
        "lastName": "Garcia",
        "email": "maria.garcia@company.com", 
        "department": "Marketing"
      }
    ]
  });
  ```
</CodeGroup>

<Frame>
  ![Process Data Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/payload_process_add.png)
</Frame>

<Warning>
  **Critical Step**: After creating your data structure, you must configure field indexing in **Process Settings → Data Search** for the search to work.
</Warning>

#### Configure field Indexing

Navigate to **Process Settings → Data Search** and add the field paths you want to search:

<Frame>
  ![Index Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/index_keys.png)
</Frame>

**Example indexed fields:**

* `application.client.personalInfo.firstName`
* `application.client.personalInfo.lastName`
* `application.client.personalInfo.email`
* `application.listClient` (array — all fields of every element are indexed automatically)

<Warning>
  **Array fields**: index the array path itself (e.g. `application.listClient`) — do **not** use `[]` notation in Process Settings. A key like `application.listClient.[].firstName` cannot be resolved and silently indexes nothing — no error is shown. The `[]` notation is used only in search requests.

  Indexing an array indexes all fields of every element. You cannot index a subset of an array's fields directly — if you need only some fields (or want to keep the index small), build a slimmed copy of the array in a business rule (e.g. `application.listClientSearch` containing only the searchable fields) and index that key instead.

  Every indexed field of every array element counts toward Elasticsearch's nested-objects-per-document limit (10,000 by default). Indexing very large arrays will fail — index a slim projection or scalar summary keys instead.
</Warning>

#### When data gets indexed to Elasticsearch

<Warning>
  **Critical**: Configuring field indexing in Process Settings is only the first step. Your data will **not** be automatically indexed to Elasticsearch just because the process finishes.
</Warning>

Data indexing to Elasticsearch occurs **only** in these specific scenarios:

| Trigger                                               | What Gets Indexed                                |
| ----------------------------------------------------- | ------------------------------------------------ |
| **Stage changes**                                     | All configured indexed fields                    |
| **Swimlane changes**                                  | All configured indexed fields                    |
| **"Update data search" flag enabled on a node**       | All configured indexed fields                    |
| **Process status changes** (STARTED → FINISHED, etc.) | Only the process status, **not** the data fields |

<Info>
  When a process instance changes status (e.g., from STARTED to FINISHED), only the status itself is updated in Elasticsearch. The actual data fields you configured for indexing are **not** automatically re-indexed at this point.
</Info>

#### Enable the "Update data search" flag

To ensure your data is indexed and searchable, you must enable the **Update data search** flag on at least one node in your process:

1. Open a node in your process definition
2. Go to **Node Config**
3. Enable the **Update data search** toggle

**Best practices for flag placement:**

* **For final data only**: Place the flag on the last node before process completion
* **For milestone tracking**: Place the flag at key checkpoints where you need searchable snapshots
* **You don't need to enable it on every node**; only enable it where you need the data to be indexed

<Tip>
  If you only need to search the final process data, enable "Update data search" on just the last node before the End Event. This minimizes unnecessary Elasticsearch updates while ensuring your completed data is searchable.
</Tip>

### 2. Create your search process

Create a new process with a **Send Message Task**:

<Frame>
  ![Search Process Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/search_topic_action.png)
</Frame>

**Configuration:**

* **Action Type**: Kafka Send Action
* **Topic**: `KAFKA_TOPIC_DATA_SEARCH_IN`

### 3. Configure search parameters

Choose your search approach based on your needs:

<Tabs>
  <Tab title="Simple Search">
    Use when searching by a single field:

    ```json theme={"system"}
    {
      "searchKey": "application.client.personalInfo.lastName",
      "value": "Johnson",
      "processDefinitionNames": ["client_process"],
      "states": ["FINISHED"]
    }
    ```

    <Frame>
      ![Simple Search Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/simple_search_payload.png)
    </Frame>
  </Tab>

  <Tab title="Advanced Search">
    Use when searching by multiple criteria (AND logic):

    ```json theme={"system"}
    {
      "searchKeys": [
        {"key": "application.client.personalInfo.firstName", "value": "Sarah"},
        {"key": "application.client.personalInfo.lastName", "value": "Johnson"}
      ],
      "processDefinitionNames": ["client_process"],
      "states": ["FINISHED"]
    }
    ```

    <Info>All conditions in `searchKeys` must match for a result to be returned.</Info>
  </Tab>

  <Tab title="Array Search">
    Use when searching within arrays or lists. You can use either `searchKeys` or `searchByPaths`:

    **Using searchKeys with array notation:**

    ```json theme={"system"}
    {
      "searchKeys": [
        {"key": "application.listClient.[].firstName", "value": "Maria"}
      ],
      "processDefinitionNames": ["client_process"],
      "states": ["FINISHED"]
    }
    ```

    **Using searchByPaths (recommended for arrays):**

    ```json theme={"system"}
    {
      "searchByPaths": [
        {"key": "application.listClient.[].firstName", "value": "Maria"}
      ],
      "processDefinitionNames": ["client_process"],
      "states": ["FINISHED"]
    }
    ```

    **Combined array search (multiple conditions in array):**

    ```json theme={"system"}
    {
      "searchByPaths": [
        {"key": "application.listClient.[].firstName", "value": "Maria"},
        {"key": "application.listClient.[].department", "value": "Engineering"}
      ],
      "processDefinitionNames": ["client_process"]
    }
    ```

    <Info>
      * Use `[]` notation to search within array elements
      * This searches through all items in the array
      * Returns processes where any array element matches the criteria
    </Info>
  </Tab>

  <Tab title="Cross-Application">
    Search across multiple applications:

    ```json theme={"system"}
    {
      "searchKey": "application.client.account.type",
      "value": "Premium",
      "applicationIds": [
        "app-1-uuid",
        "app-2-uuid"
      ]
    }
    ```
  </Tab>

  <Tab title="Date Filtering">
    Filter by process creation dates:

    ```json theme={"system"}
    {
      "searchKey": "application.client.business.industry",
      "value": "Technology",
      "processStartDateAfter": "2024-01-01T00:00:00Z",
      "processStartDateBefore": "2024-12-31T23:59:59Z",
      "states": ["FINISHED"]
    }
    ```
  </Tab>
</Tabs>

### 4. Handle search results

Add a **Receive Message Task** with:

* **Data Stream**: `KAFKA_TOPIC_DATA_SEARCH_OUT`

<Frame>
  ![Receive Search Results](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/receive_data_search.png)
</Frame>

**Success response example:**

<Frame>
  ![Search Results](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/result_simple.png)
</Frame>

<CodeGroup>
  ```json Success Response theme={"system"}
  {
    "result": [
      {
        "processInstanceUUID": "b743ac99-4029-4b93-9ac3-4a45b4a62673",
        "state": "FINISHED",
        "processStartDate": "2025-05-28T12:18:50.532Z",
        "data": {
          "application": {
            "client": {
              "personalInfo": {
                "firstName": "Sarah",
                "lastName": "Johnson"
              }
            }
          }
        }
      }
    ],
    "tooManyResults": false,
    "success": true
  }
  ```

  ```json Array Search Response theme={"system"}
  {
    "result": [
      {
        "processInstanceUUID": "c854bd10-5140-5c04-0bd4-5b56c5b73784",
        "state": "FINISHED", 
        "processStartDate": "2025-05-28T14:22:15.847Z",
        "data": {
          "application": {
            "listClient": [
              {
                "firstName": "Maria",
                "lastName": "Rodriguez",
                "email": "maria.rodriguez@company.com",
                "department": "Engineering"
              },
              {
                "firstName": "Maria", 
                "lastName": "Garcia",
                "email": "maria.garcia@company.com",
                "department": "Marketing"
              }
            ]
          }
        }
      }
    ],
    "tooManyResults": false,
    "success": true
  }
  ```

  ```json No Results Response theme={"system"}
  {
    "result": [],
    "searchKey": "application.client.personalInfo.lastName",
    "searchValue": "Smith",
    "tooManyResults": false,
    "success": true
  }
  ```
</CodeGroup>

## Search parameters reference

### Quick reference table

| Parameter                | Type   | Mandatory                | Description                            | Example                                      |
| ------------------------ | ------ | ------------------------ | -------------------------------------- | -------------------------------------------- |
| `searchKey`              | String | Yes                      | Single field path to search            | `"application.client.personalInfo.lastName"` |
| `value`                  | String | Yes                      | Value to search for (with searchKey)   | `"Johnson"`                                  |
| `searchKeys`             | Array  | Yes (if multiple fields) | Multiple field-value pairs (AND logic) | `[{"key": "field1", "value": "val1"}]`       |
| `searchByPaths`          | Array  | Yes (for array search)   | Array search field-value pairs         | `[{"key": "list.[].field", "value": "val"}]` |
| `processDefinitionNames` | Array  | Yes                      | Limit to specific processes            | `["client_onboarding"]`                      |
| `applicationIds`         | Array  | No                       | Search across applications             | `["uuid-1", "uuid-2"]`                       |
| `states`                 | Array  | No                       | Filter by process states               | `["FINISHED", "STARTED"]`                    |
| `processStartDateAfter`  | String | No                       | Include processes after date           | `"2024-01-01T00:00:00Z"`                     |
| `processStartDateBefore` | String | No                       | Include processes before date          | `"2024-12-31T23:59:59Z"`                     |

### Basic search parameters

<AccordionGroup>
  <Accordion title="searchKey (String)">
    **Purpose**: The field path to search in for single-field searches.

    **Usage**: Use dot notation to specify the exact path to the field you want to search or a specific key in the payload.

    **Examples**:

    * `"application.client.personalInfo.firstName"`
    * `"application.client.address.city"`
    * `"application.client.business.industry"`

    **Important**: This field must be indexed in Process Settings → Data Search to work.

    <Warning>Cannot be used together with `searchKeys` or `searchByPaths`. Choose one approach.</Warning>
  </Accordion>

  <Accordion title="value (String)">
    **Purpose**: The exact value to search for when using `searchKey`.

    **Usage**: Must match the stored value exactly (case-sensitive).

    **Examples**:

    * `"Johnson"` - searches for exact lastName match
    * `"Technology"` - searches for exact industry match
    * `"Active"` - searches for exact status match

    **Note**: Only used with `searchKey`, not with `searchKeys` or `searchByPaths`.
  </Accordion>

  <Accordion title="searchKeys (Array)">
    **Purpose**: Array of key-value pairs for multi-field searches with AND logic.

    **Usage**: All conditions must match for a result to be returned. Can also be used for array searches with `[]` notation.

    **Format**:

    ```json theme={"system"}
    [
      {"key": "field.path.1", "value": "value1"},
      {"key": "field.path.2", "value": "value2"}
    ]
    ```

    **Examples**:

    ```json theme={"system"}
    [
      {"key": "application.client.personalInfo.firstName", "value": "Sarah"},
      {"key": "application.client.business.industry", "value": "Technology"}
    ]
    ```

    **Array Search Example**:

    ```json theme={"system"}
    [
      {"key": "application.listClient.[].firstName", "value": "Maria"}
    ]
    ```

    <Warning>Cannot be used together with `searchKey` or `searchByPaths`. Choose one approach.</Warning>
  </Accordion>

  <Accordion title="searchByPaths (Array)">
    **Purpose**: Array of key-value pairs specifically designed for searching within array elements and nested structures.

    **Usage**: Use `[]` notation to search within array elements. This searches through all items in the array and is the recommended approach for array searches.

    **Format**:

    ```json theme={"system"}
    [
      {"key": "arrayfield.[].property", "value": "searchvalue"}
    ]
    ```

    **Examples**:

    ```json theme={"system"}
    [
      {"key": "application.listClient.[].firstName", "value": "Maria"}
    ]
    ```

    **Multiple Array Conditions**:

    ```json theme={"system"}
    [
      {"key": "application.listClient.[].firstName", "value": "Maria"},
      {"key": "application.listClient.[].department", "value": "Engineering"}
    ]
    ```

    **Nested Array Example**:

    ```json theme={"system"}
    [
      {"key": "application.clients.[].addresses.[].city", "value": "New York"}
    ]
    ```

    <Info>
      * **Recommended** for array searches over `searchKeys`
      * Returns processes where any array element matches the criteria
      * Supports deeply nested array structures
    </Info>

    <Warning>Cannot be used together with `searchKey` or `searchKeys`. Choose one approach.</Warning>
  </Accordion>
</AccordionGroup>

### Filtering parameters

<AccordionGroup>
  <Accordion title="processDefinitionNames (Array)">
    **Purpose**: Limit search to specific process definitions.

    **Default**: Searches all processes if omitted.

    **Usage**: Improves performance by narrowing search scope.

    **Examples**:

    * `["client_onboarding"]` - search only in client processes
    * `["employee_registration", "contractor_onboarding"]` - search in multiple process types

    **Best Practice**: Always specify to improve search performance.
  </Accordion>

  <Accordion title="applicationIds (Array)">
    **Purpose**: Search across specific applications.

    **Default**: Searches current application if omitted.

    **Usage**: Enable cross-application searches.

    **Examples**:

    * `["8dd20844-2dc5-4445-83a5-bbbcc82bed5f"]` - search in specific app
    * `["app-1-uuid", "app-2-uuid", "app-3-uuid"]` - search across multiple apps

    **Use Case**: Useful for consolidated reporting across different business units.
  </Accordion>

  <Accordion title="states (Array)">
    **Purpose**: Filter results by process instance status.

    **Default**: Returns all states if omitted.

    **Available States**:

    * `"CREATED"` - Process instance created but not started
    * `"STARTED"` - Process is currently running
    * `"FINISHED"` - Process completed successfully
    * `"FAILED"` - Process encountered an error and stopped
    * `"TERMINATED"` - Process was manually stopped/cancelled
    * `"ONHOLD"` - Process is paused or waiting for external input

    **Examples**:

    * `["FINISHED"]` - only completed processes
    * `["STARTED", "ONHOLD"]` - active or paused processes
    * `["FAILED", "TERMINATED"]` - processes that didn't complete normally

    **Best Practice**: Use `["FINISHED"]` for most business searches to get complete data.
  </Accordion>
</AccordionGroup>

### Date range parameters

<AccordionGroup>
  <Accordion title="processStartDateAfter (String)">
    **Purpose**: Include only processes started after the specified date.

    **Format**: ISO 8601 timestamp (`YYYY-MM-DDTHH:MM:SSZ`)

    **Examples**:

    * `"2024-01-01T00:00:00Z"` - processes started after Jan 1, 2024
    * `"2024-06-15T09:30:00Z"` - processes started after June 15, 2024 at 9:30 AM

    **Use Cases**:

    * Monthly reports: `"2024-03-01T00:00:00Z"`
    * Recent activity: `"2024-05-20T00:00:00Z"`
  </Accordion>

  <Accordion title="processStartDateBefore (String)">
    **Purpose**: Include only processes started before the specified date.

    **Format**: ISO 8601 timestamp (`YYYY-MM-DDTHH:MM:SSZ`)

    **Examples**:

    * `"2024-12-31T23:59:59Z"` - processes started before end of 2024
    * `"2024-06-30T23:59:59Z"` - processes started before end of June 2024

    **Use Cases**:

    * Historical analysis: `"2024-01-01T00:00:00Z"`
    * Quarterly reports: `"2024-03-31T23:59:59Z"`
  </Accordion>
</AccordionGroup>

### Process states explained

Understanding process states is crucial for effective searching:

| State          | Description                                          | When to Use                              |
| -------------- | ---------------------------------------------------- | ---------------------------------------- |
| **CREATED**    | Process instance exists but hasn't started execution | Rarely used for business searches        |
| **STARTED**    | Process is actively running                          | Find ongoing processes, current workload |
| **FINISHED**   | Process completed successfully                       | Most common for business data searches   |
| **FAILED**     | Process encountered an error                         | Error analysis, troubleshooting          |
| **TERMINATED** | Process was manually cancelled                       | Audit trails, cancelled applications     |
| **ONHOLD**     | Process is paused/waiting                            | Active cases needing attention           |

<Info>
  **Recommendation**: Use `["FINISHED"]` for most business searches to ensure you're getting complete, reliable data.
</Info>

### Response structure

The search returns a JSON object with these fields:

* **`result`** (Array): List of matching process instances
  * `processInstanceUUID`: Unique process identifier
  * `state`: Current process state
  * `processStartDate`: When the process started
  * `data`: The actual process data with your searchable fields
* **`tooManyResults`** (Boolean): True if more than 50 results found (limit applied)
* **`success`** (Boolean): Whether the search completed successfully
* **`errorMessage`** (String): Error details if search failed

## Use cases & examples

<CardGroup>
  <Card title="HR employee lookup" icon="users">
    Search for employees by department, position, or location across HR systems.
  </Card>

  <Card title="Compliance Auditing" icon="shield-check">
    Locate specific transactions or approvals for regulatory compliance.
  </Card>

  <Card title="Business Intelligence" icon="chart-bar">
    Analyze process data patterns and generate reports.
  </Card>

  <Card title="Multi-contact Search" icon="address-book">
    Find processes containing specific individuals within contact lists or arrays.
  </Card>
</CardGroup>

### Real-world example: Employee directory search

<Steps>
  <Step title="HR needs to find employees">
    HR department needs to find all employees named "Maria" across different departments.
  </Step>

  <Step title="Search within employee arrays">
    ```json theme={"system"}
    {
      "searchByPaths": [
        {"key": "application.employees.[].firstName", "value": "Maria"}
      ],
      "processDefinitionNames": ["employee_onboarding"],
      "states": ["FINISHED"]
    }
    ```
  </Step>

  <Step title="Get comprehensive results">
    Receive all employee records containing anyone named "Maria" in their employee lists.
  </Step>

  <Step title="Refine search if needed">
    Add additional criteria like department or role to narrow results further.
  </Step>
</Steps>

### Real-world example: Customer support search

<Steps>
  <Step title="Customer calls with issue">
    Support agent needs to find customer's account quickly.
  </Step>

  <Step title="Search by multiple criteria">
    ```json theme={"system"}
    {
      "searchKeys": [
        {"key": "customer.email", "value": "customer@email.com"},
        {"key": "customer.status", "value": "Active"}
      ],
      "processDefinitionNames": ["customer_onboarding"],
      "states": ["FINISHED"]
    }
    ```
  </Step>

  <Step title="Get comprehensive results">
    Receive full customer profile with account details, order history, and support tickets.
  </Step>

  <Step title="Resolve customer issue">
    Use the retrieved data to address the customer's concern effectively.
  </Step>
</Steps>

***

## Best practices

<AccordionGroup>
  <Accordion title="Indexing Strategy">
    * **Always enable "Update data search"** on at least one node to trigger data indexing
    * **If you don't have stages or swimlanes configured**, the "Update data search" flag is your **only way** to index data - without it, your data fields won't be searchable
    * **Place the flag strategically**: on the last node for final data, or at milestones for intermediate snapshots
    * **Don't enable on every node**: this creates unnecessary Elasticsearch updates
    * **Remember**: Process status changes (like finishing) only update the status in Elasticsearch, not your data fields
    * **For long processes**, consider enabling at key checkpoints to make data searchable earlier
  </Accordion>

  <Accordion title="Array Search Optimization">
    * **Use searchByPaths** for array searches instead of searchKeys when possible
    * **Index array fields by their array path** (e.g. `application.listClient`) in Process Settings — `[]` notation is used only in search requests
    * **Consider array size** - large arrays may impact search performance
    * **Combine array searches** with filters to reduce result sets
    * **Test nested array searches** thoroughly before deploying to production
  </Accordion>

  <Accordion title="Performance optimization">
    * **Limit search scope** using `processDefinitionNames` and `states`
    * **Use date ranges** for time-sensitive searches
    * **Index only frequently searched fields** to reduce storage overhead
    * **Monitor search response times** and optimize queries
    * **Avoid wildcard searches** on large datasets
  </Accordion>

  <Accordion title="Data Modeling">
    * **Use consistent field naming** across processes
    * **Normalize data formats** (dates, phone numbers, etc.)
    * **Consider search patterns** when designing data structures
    * **Document indexed fields** for team reference
    * **Plan for data growth** and scaling needs
    * **Design arrays with search in mind** - consider what fields will be searched
  </Accordion>

  <Accordion title="Security & Compliance">
    * **Don't index sensitive data** (SSN, passwords, etc.)
    * **Implement proper access controls** for search endpoints
    * **Log search activities** for audit trails
    * **Sanitize search inputs** to prevent injection attacks
    * **Follow data retention policies** for search results
  </Accordion>

  <Accordion title="Error Handling">
    * **Handle empty results** gracefully in your UI
    * **Implement retry logic** for failed searches
    * **Provide meaningful error messages** to users
    * **Set reasonable timeouts** for search operations
    * **Monitor and alert** on search failures
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Search Results">
    **Possible Causes:**

    * **"Update data search" flag not enabled** on any node (most common cause)
    * Fields not indexed in Process Settings → Data Search
    * Incorrect field path (case-sensitive)
    * Process instances not in expected state
    * Elasticsearch indexing delay
    * Array notation missing for array searches

    **Solutions:**

    * **Enable "Update data search"** on at least one node (typically the last node before completion)
    * Verify field indexing configuration in Process Settings → Data Search
    * Check exact field paths in process data
    * Ensure processes are in FINISHED state
    * Wait 30-60 seconds after process completion
    * Use `[]` notation for array field searches
  </Accordion>

  <Accordion title="Data Not Indexed Despite Process Completion">
    **Possible Causes:**

    * "Update data search" flag not enabled on any node
    * Misunderstanding of when indexing occurs (status changes only update the status, not data)
    * Data added after the last node with the flag enabled

    **Solutions:**

    * Enable "Update data search" on the last node before the End Event
    * Remember: process status changes (STARTED → FINISHED) only index the status, not your data fields
    * Place the "Update data search" flag after all data has been collected
    * For milestone-based indexing, enable the flag at each checkpoint where you need searchable data
  </Accordion>

  <Accordion title="Array Search Issues">
    **Possible Causes:**

    * Missing `[]` notation in field path
    * Array fields not properly indexed
    * Using wrong parameter (`searchKeys` vs `searchByPaths`)
    * Array is empty or doesn't contain expected data

    **Solutions:**

    * Ensure field path includes `[]` for arrays (e.g., `list.[].field`)
    * Verify array fields are indexed by their array path (e.g. `application.listClient`), not `[]` notation — index keys containing `[]` silently index nothing
    * Use `searchByPaths` for array searches when possible
    * Check that arrays contain the expected data structure
    * Test with simple array structures first
  </Accordion>

  <Accordion title="Search Timeout Errors">
    **Possible Causes:**

    * Query too broad (searching all data)
    * Elasticsearch cluster performance issues
    * Large dataset without proper filtering
    * Complex nested array searches

    **Solutions:**

    * Add more specific filters (`processDefinitionNames`, `states`)
    * Use date ranges to limit scope
    * Check Elasticsearch cluster health
    * Optimize indexing strategy
    * Simplify complex array search patterns
  </Accordion>

  <Accordion title="Invalid Search Key Errors">
    **Possible Causes:**

    * Typos in field paths
    * Field doesn't exist in process data
    * Incorrect JSON format in request
    * Missing array notation for array fields

    **Solutions:**

    * Verify field paths exist in process instances
    * Check for case sensitivity
    * Validate JSON syntax
    * Test with simple field paths first
    * Add `[]` notation for array field searches
  </Accordion>

  <Accordion title="Connection Issues">
    **Possible Causes:**

    * Kafka topics not properly configured
    * Network connectivity problems
    * Service authentication issues

    **Solutions:**

    * Verify Kafka topic configuration
    * Check network connectivity
    * Validate service credentials
    * Review FlowX Engine logs
  </Accordion>
</AccordionGroup>

***

## Configuration templates

<CodeGroup>
  ```json Simple search template theme={"system"}
  {
    "searchKey": "your.field.path",
    "value": "search_value",
    "processDefinitionNames": ["your_process"],
    "states": ["FINISHED"]
  }
  ```

  ```json Advanced search template theme={"system"}
  {
    "searchKeys": [
      {"key": "field1", "value": "value1"},
      {"key": "field2", "value": "value2"}
    ],
    "processDefinitionNames": ["your_process"],
    "states": ["FINISHED"]
  }
  ```

  ```json Array search template (searchKeys) theme={"system"}
  {
    "searchKeys": [
      {"key": "application.listField.[].property", "value": "search_value"}
    ],
    "processDefinitionNames": ["your_process"],
    "states": ["FINISHED"]
  }
  ```

  ```json Array search template (searchByPaths) theme={"system"}
  {
    "searchByPaths": [
      {"key": "application.listField.[].property", "value": "search_value"}
    ],
    "processDefinitionNames": ["your_process"],
    "states": ["FINISHED"]
  }
  ```

  ```json Multiple array conditions template theme={"system"}
  {
    "searchByPaths": [
      {"key": "application.employees.[].firstName", "value": "Maria"},
      {"key": "application.employees.[].department", "value": "Engineering"}
    ],
    "processDefinitionNames": ["employee_process"]
  }
  ```

  ```json Cross-application template theme={"system"}
  {
    "searchKey": "your.field.path",
    "value": "search_value",
    "applicationIds": ["app-uuid-1", "app-uuid-2"],
    "states": ["FINISHED"]
  }
  ```

  ```json Date range template theme={"system"}
  {
    "searchKey": "your.field.path",
    "value": "search_value",
    "processStartDateAfter": "2024-01-01T00:00:00Z",
    "processStartDateBefore": "2024-12-31T23:59:59Z",
    "processDefinitionNames": ["your_process"]
  }
  ```
</CodeGroup>

***

## Related resources

<CardGroup>
  <Card title="Elasticsearch setup" href="../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/" icon="gears">
    Configure Elasticsearch indexing for FlowX Engine
  </Card>

  <Card title="Data search service setup" href="../../../setup-guides/search-data-service-setup-guide" icon="server">
    Complete deployment and configuration guide
  </Card>

  <Card title="Process designer" href="../../building-blocks/process/process" icon="diagram-project">
    Learn how to design processes with searchable data
  </Card>
</CardGroup>


# Task Management localization
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization

Comprehensive localization support for Task Management, enabling multi-language experiences through FlowX substitution tags.

Task Management in FlowX.AI includes comprehensive localization capabilities, allowing you to deliver fully translated task management interfaces in multiple languages. Configure 51 FlowX substitution tags in CMS for each language you want to support.

## Localization approach

Task Management localization operates through FlowX Substitution Tags:

### FlowX Substitution Tags (51 Keys) - manual configuration

Custom Task Management UI elements that **must be configured manually in CMS** for each language:

* Table column names (title, stage, assignee, status, priority)
* Task actions (assign, unassign, hold, execute)
* Bulk operations (assign all to me, unassign all, hold all)
* History events and status values
* Comments and user selection dialogs

<Info>
  If you need to configure FlowX substitution tags default text values (51 keys) in CMS, you can do so by navigating to **CMS** → **Substitution Tags** and adding the default text values for the substitution tags.
</Info>

## FlowX substitution tags

FlowX substitution tags control custom Task Management interface elements outside the data table. These **51 tags** must be configured manually in CMS for each language.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
</Frame>

### Complete tag reference

<Tabs>
  <Tab title="Search & columns">
    **Search & Navigation**

    * `sys_tm_search` - "Search"

    **Table Columns**

    * `sys_tm_title` - "Title"
    * `sys_tm_stage` - "Stage"
    * `sys_tm_assignee` - "Assignee"
    * `sys_tm_status` - "Status"
    * `sys_tm_priority` - "Priority"
    * `sys_tm_last_updated` - "Last updated"
  </Tab>

  <Tab title="Process states">
    **Process States (Status Values)**

    * `sys_tm_created` - "Created"
    * `sys_tm_started` - "Started"
    * `sys_tm_finished` - "Finished"
    * `sys_tm_finished_with_error` - "Finished with error"
    * `sys_tm_failed` - "Failed"
    * `sys_tm_expired` - "Expired"
    * `sys_tm_aborted` - "Aborted"
    * `sys_tm_terminated` - "Terminated"
    * `sys_tm_dismissed` - "Dismissed"
    * `sys_tm_on_hold` - "On hold"
  </Tab>

  <Tab title="Actions">
    **Bulk Actions**

    * `sys_tm_assign_to` - "Assign to…"
    * `sys_tm_unassign_all` - "Unassign All"
    * `sys_tm_assign_all_to_me` - "Assign All to me"
    * `sys_tm_hold_all` - "Hold All"
    * `sys_tm_unhold_all` - "Unhold All"

    **Task Actions**

    * `sys_tm_view_application` - "View Application"
    * `sys_tm_unassign` - "Unassign"
    * `sys_tm_assign_to_myself` - "Assign to myself"
    * `sys_tm_unhold` - "Unhold"
    * `sys_tm_hold` - "Hold"
    * `sys_tm_assign` - "Assign"
    * `sys_tm_execute` - "Execute"
    * `sys_tm_start` - "Start"
  </Tab>

  <Tab title="Task details">
    **Task Details Sections**

    * `sys_tm_assignee_deactivated` - "(Deactivated)"
    * `sys_tm_comments` - "Comments"
    * `sys_tm_write_a_comment` - "Write a comment…"
    * `sys_tm_history` - "History"

    **History Events**

    * `sys_tm_task_created` - "Task created"
    * `sys_tm_user_created_this_task` - "`${user}` created this task"
    * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
    * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
    * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
    * `sys_tm_task_moved_to` - "Task moved to"
    * `sys_tm_task_status_changed_to` - "Task status changed to"
    * `sys_tm_task_assigned_to` - "Task assigned to"
    * `sys_tm_task_owner_removed` - "Task owner removed"
  </Tab>

  <Tab title="User selection & UI">
    **User Selection & Search**

    * `sys_tm_select_person` - "Select person..."
    * `sys_tm_search_person` - "Search users"
    * `sys_tm_search_term_validation` - "Type at least 4 characters..."

    **UI States**

    * `sys_tm_loading` - "Loading..."
    * `sys_tm_nothing_found` - "Nothing Found"

    **Data display**

    * `sys_tm_in` - "In" (custom filter operator)
    * `sys_tm_yes` - "Yes" (boolean value)
    * `sys_tm_no` - "No" (boolean value)
  </Tab>
</Tabs>

<Warning>
  **Manual Configuration Required**: All 51 FlowX substitution tags must be configured manually in CMS for each language you want to support. They control custom Task Management UI elements outside of the data table.
</Warning>

## Implementation guide

To localize Task Management, configure the **51 FlowX substitution tags** in CMS for each language you want to support.

<Steps>
  <Step title="Add FlowX substitution tags to CMS">
    For each supported language:

    1. Navigate to **CMS** → **Substitution Tags**
    2. Add values for all 51 `sys_tm_*` tags for the target language
    3. These control custom Task Management UI elements:
       * Task actions (assign, hold, unassign)
       * Bulk operations (assign all to me, unassign all, hold all, unhold all)
       * History events (task created, user created this task, started process instance with id, started process instance on build, task ownership changed to, task moved to, task status changed to, task assigned to, task owner removed)
       * Comments section (comments, write a comment...)
       * User selection dialogs (select person, search users, search term validation)
       * UI states (loading, nothing found)
       * Data display (in, yes, no)
  </Step>

  <Step title="Configure custom column names (Optional)">
    If you need columns beyond the default ones:

    1. Define custom parameters in **Process Settings** → **Task Management**
    2. Use substitution tags for column display names
    3. These tags will also need CMS translations for each language
    4. When you configure the column display name, use the substitution tag for the column name( it is called using "@@" prefix)
  </Step>

  <Step title="Test localization">
    Verify that Task Management is properly localized:

    * Task action buttons (assign, unassign, hold, execute)
    * Bulk operation buttons (assign all to me, unassign all, hold all)
    * Task history timeline and status values
    * Comments section and user assignment dialogs
  </Step>
</Steps>

## Localization best practices

### 1. Maintain consistency

Ensure translation consistency across:

* CMS substitution tags
* Custom column display names

### 2. Handle dynamic content

For history events and comments that include dynamic values (user names, dates, IDs), use the variable placeholders:

```javascript theme={"system"}
// In CMS, use placeholders
sys_tm_user_created_this_task: "${user} created this task"
sys_tm_task_assigned_to: "Task assigned to ${user}"

// The system will replace ${user} with actual usernames at runtime
```

## Localization by component

### Task list view

| Component                | Configuration Required |
| ------------------------ | ---------------------- |
| Column headers (default) | CMS translation        |
| Column headers (custom)  | CMS translation        |
| Search placeholder       | CMS translation        |
| Status values            | CMS translation        |

### Task details panel

| Component        | Configuration Required |
| ---------------- | ---------------------- |
| Action buttons   | CMS translation        |
| Section titles   | CMS translation        |
| History timeline | CMS translation        |
| Comment input    | CMS translation        |
| User selector    | CMS translation        |

### Bulk operations

| Component              | Configuration Required |
| ---------------------- | ---------------------- |
| Bulk action buttons    | CMS translation        |
| Confirmation dialogs   | CMS translation        |
| Success/error messages | CMS translation        |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Custom elements not translating">
    **Problem**: Task actions, history, or comments display in English.

    **Solutions**:

    1. Verify all 51 `sys_tm_*` tags are configured in CMS
    2. Check that translations exist for the current user's language
    3. Ensure CMS language codes match your application's language selection
    4. Verify substitution tag syntax is correct (no typos)
  </Accordion>

  <Accordion title="Mixed language display">
    **Problem**: Some elements in one language, others in another.

    **Solutions**:

    1. This indicates incomplete CMS configuration - likely missing FlowX substitution tags
    2. Verify all 51 `sys_tm_*` tags are translated in CMS for the target language
    3. Use browser dev tools to identify which specific elements are untranslated
  </Accordion>

  <Accordion title="Custom column names not translating">
    **Problem**: Custom columns display original names instead of translations.

    **Solutions**:

    1. Ensure custom column display names use substitution tags
    2. Verify those substitution tags are configured in CMS for all languages
    3. Check that column configuration points to correct substitution tag keys
  </Accordion>
</AccordionGroup>

## Example: complete Romanian localization

Here's an example of configuring Task Management for Romanian language:

<Steps>
  <Step title="Add Romanian CMS translations">
    In CMS, add translations for all 51 tags:

    ```json theme={"system"}
    {
      "sys_tm_search": "Căutare",
      "sys_tm_title": "Titlu",
      "sys_tm_stage": "Etapă",
      "sys_tm_assignee": "Asignat",
      "sys_tm_status": "Status",
      "sys_tm_priority": "Prioritate",
      "sys_tm_last_updated": "Ultima actualizare",
      "sys_tm_created": "Creat",
      "sys_tm_started": "Început",
      "sys_tm_finished": "Finalizat",
      "sys_tm_assign_to": "Atribuie către…",
      "sys_tm_unassign": "Anulează atribuirea",
      "sys_tm_comments": "Comentarii",
      "sys_tm_history": "Istoric",
      // ... add all 51 tags
    }
    ```
  </Step>

  <Step title="Verify complete localization">
    Test all areas to confirm:

    * ✅ Task actions show Romanian labels (from CMS)
    * ✅ History events display in Romanian (from CMS)
    * ✅ Comments section uses Romanian labels (from CMS)
  </Step>
</Steps>

## Additional resources

<CardGroup>
  <Card title="Task Management Overview" href="./task-management-overview" icon="list-check">
    Learn about Task Management features and configuration
  </Card>

  <Card title="CMS Substitution Tags" href="../content-management/substitution-tags" icon="tags">
    Configure substitution tags in Content Management System
  </Card>
</CardGroup>


# Task management
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-overview

Task Management tracks work items generated by running processes, giving teams visibility into who is doing what and where each case stands. One task is created per process instance.

<Frame>
  ![Task Manager](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/tsk_mng2.0.png)
</Frame>

Task Management tracks work items generated by running processes. It gives teams visibility into who is responsible for each case, where it stands, and what needs attention. It supports both low-code (built-in views) and full-code (SDK-based) approaches.

***

## How it works

### Tasks and process instances

When a process instance starts, FlowX creates **one task** for that instance. The task acts as a container that tracks everything happening inside the process: which swimlane the work is in, who is assigned, what stage it has reached, and what its status is.

The relationship is **one task per process instance**, not per user or per node.

### Tokens and swimlanes

Inside a task, FlowX tracks individual **tokens** as they move through swimlanes and stages. Each time a token enters or exits a swimlane or stage, Task Management records that transition. This means a single task can reflect activity across multiple swimlanes if the process is designed that way.

### Parallel gateways

When a process reaches a parallel gateway and splits into multiple paths:

* The **parent token** is paused (`ON_HOLD`) while child tokens execute in parallel.
* Each **child token** is tracked independently inside the same task.
* If multiple tokens land in the **same swimlane**, Task Management automatically deduplicates them so the task list shows a single entry per swimlane.
* When all parallel paths complete and the gateway joins, the parent token resumes.

### Enabling task management for a process

Before Task Management can track a process, you must enable it:

1. In **FlowX Designer**, open the process definition and go to **Process Settings** → **Task Management** tab.
2. Toggle **Use process in task management** to **ON**.

<Warning>
  This toggle is required. If it is off, no task will be created for instances of this process, and no updates will be sent to Task Management.
</Warning>

Once enabled, you can also configure which nodes send updates to Task Management by enabling the **Update task management** switch on individual nodes. This controls whether task metadata (title, priority, stage, business filters) is refreshed when the token passes through that node.

***

## Key features

* **Views**: Configurable interfaces to display task-related data, scoped to a process definition.
* **Stages**: Monitor the progression of tasks within a process by identifying where a case may have stalled. Useful for tracking business stages like onboarding, verification, and validation.
* **Allocation rules**: Automatically distribute tasks among users based on current workload. The user with the fewest assigned tasks in the target swimlane is selected.
* **Localization** (Available in 5.1.1+): Multi-language support with 34+ languages. Configure substitution tags in CMS while table grid localization happens automatically. See [**Task Management Localization**](./task-management-localization) for details.

## Task Management Views

Views offer a flexible way to tailor task data display according to business needs. By configuring views, users can create structured, customized interfaces that help specific roles, departments, or use cases access relevant data effectively.

Example of custom view:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2016.29.13.png)
</Frame>

### All tasks

In the All Tasks section, you can view all tasks generated from any process definition marked as "to be used in task manager" within a project. This provides a centralized view of all relevant tasks, as long as you have the appropriate permissions.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-11%20at%2018.32.13.png)
</Frame>

It provides an interactive visualization, with built-in filtering functionalities for refined data display.

<Info>
  Dataset Config and Table Config options are not accessible in the All Tasks view.
</Info>

### Creating a view

In the Views section, you can create a new view by selecting a name and choosing a process definition. The process definition is crucial because it determines which keys you can access when configuring the view.

To set up a view, navigate to the Views section in the Task Management interface:

1. Click **Add View**.
2. Enter a **Name** for the view.
3. **Choose a Process Definition**: This will link the view's configuration to a specific process and its associated keys.

<Info>
  Once a view is created for a process (e.g., Process X), it cannot be reassigned to another process. This ensures consistent data structuring based on the selected process definition.
</Info>

Upon creating a view, you are automatically redirected to configure its parameters.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-11%2018.34.39.gif)
</Frame>

The Task Management default view contains four primary columns, with two additional default columns that can be added.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-11%20at%2018.37.30.png)
</Frame>

<Tip>
  You also have the option to add custom parameters to the table, with no limit on the number of columns.
</Tip>

**Columns explained**:

* **Stage**: Indicates where the process halted, providing a clear view of its current state.
* **Assignee**: Displays the individual to whom the task is assigned.
* **Priority**: A numeric value set via business rules, used for sorting and filtering tasks in views.
* **Last Updated**: Shows the timestamp of the most recent action taken on the task.
* **Title**: Displays the designated name of the task, which can be customized by using Business Rules.
* **Status**: The current process instance status, such as `STARTED` or `FINISHED`. See [Process status updates](#process-status-updates) for all values.
* **Custom parameters**: User-defined keys within the process settings, which become available only after their configuration is complete.

### Custom parameters and display names

### Display names

You can rename default and custom parameters to make them contextually relevant for various business needs. For example:

* Rename an address field to clarify if it refers to "Residence" or "Issuing Location."

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-11%2019.13.07.gif)
</Frame>

* Use Substitution Tags for dynamic display names.

<Info>
  Renaming a parameter's Display Name will only change how it's shown in the interface, without altering the actual data model. The rename option is also available for default parameters (not just custom parameters). Changing the Display Name also allows the use of Substitution Tags.

  For multi-language support, configure substitution tags in CMS for each language. See [**Task Management Localization**](./task-management-localization) for complete localization setup.
</Info>

### Custom Parameters in Task Management

Custom parameters in Task Management provide a way to tailor task displays and ensure that task data aligns with specific business needs and contexts.

**Key setup and configuration**

1. **Adding Custom Parameters**:
   * In **Process Settings** → **Task Management**, you can define the custom keys that will be indexed and made available for tasks.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-11%20at%2019.11.02.png)
</Frame>

* Each custom parameter can be renamed to suit different business contexts, ensuring clarity in cases where parameters may have multiple meanings.

<Check>
  Ensure that the custom key exists in the **Data Model** before it can be mapped in Task Management.

  <Warning>
    If the **attribute type** of a custom key is modified after it has been indexed, the key must be re-indexed in the **Task Management** section. This re-indexing step is crucial to ensure that Task Management reflects the updated attribute type correctly.
  </Warning>

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2010.38.23.png)
  </Frame>
</Check>

<Tip>
  For data from custom parameters to flow correctly, ensure that **Forms to Validate** is set on the button's **event handler** in your UI for the corresponding process. This configuration is necessary for custom parameters to be validated and included in Task Management.
</Tip>

2. **Labeling Custom Parameters**:
   * When adding a custom parameter, use the rename option to assign it a label relevant to the process context (as demonstrated in the example [above](#display-names)).
   * This allows parameters to remain flexible for different roles or departments, adapting to each use case.

<Frame>
  <video />
</Frame>

<Info>
  Remember to enable the **Use process in task management** toggle in **Process Settings** → **Task Management** and the **Update task management** switch on relevant nodes. See [Enabling task management for a process](#enabling-task-management-for-a-process) for details.
</Info>

### Table config and Dataset config in Task Management

You can use **Table Config** and **Dataset Config** to configure and filter task data effectively. These configurations help create a customized and user-friendly interface for different roles, departments, or organizational needs.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2013.41.17.png)
</Frame>

#### Table config

**Table Config** is used to define the structure and content of the Task Management table view. Here, you can configure the columns displayed in the table and set up default sorting options.

1. **Configuring the Table Columns**:
   * **Default Columns**: By default, the table includes the following columns: **Stage**, **Assignee**, **Priority**, and **Last Updated**.
   * You can add additional columns, such as **Title**, **Status**, and **Custom Parameters**. Custom parameters can be chosen from the keys configured in **Process Settings** → **Task Management**.

2. **Setting Default Sorting**:
   * You can select one column for **default sorting** in ascending or descending order. This configuration helps prioritize how data is initially displayed, often based on “Last Updated” or other relevant fields.
   * If no specific sorting rule is configured, the table will automatically apply sorting based on the **Last Updated** column.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2013.54.57.png)
</Frame>

#### Dataset config

**Dataset Config** is used to filter and refine the data displayed in Task Management views. This helps create targeted views based on specific needs, such as differentiating data for front office vs. back office or specific roles like managers and operators.

1. **Adding Filters**:
   * You can apply filters on the keys brought into the **Dataset Config** to customize the data shown. Filters can be applied based on various data types, such as enums, strings, numbers, dates, and booleans.

2. **Filtering Options by Data Type**:
   * **Enums**: Can be filtered using the `In` operator. Only parent enums are available for mapping in Task Management (ensure enums are mapped in the data model beforehand).

<Info>
  Before you can map enums in Task Management, they must be configured in the Data Model. Only parent enums can be mapped.

  <Warning>
    If any changes are made to the Data Model after the keys have been configured and indexed in Task Management, these changes will not be automatically reflected. You must re-add and re-index the keys in the process settings to ensure that the updated information is indexed correctly.
  </Warning>
</Info>

### View filter operators reference

The following table provides a comprehensive reference of all available view filter operators and their compatible data types:

| Filter Operator           | Compatible Data Types                                                    | Description                                                           |
| ------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **Equals**                | STRING, BOOLEAN, DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values that are exactly equal to the specified value          |
| **Not Equals**            | STRING, DATE\_TIME, ZONED\_DATE\_TIME                                    | Matches values that are not equal to the specified value              |
| **In**                    | STRING, ENUM                                                             | Matches values that are contained within a specified list             |
| **Greater Than**          | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY                  | Matches values that are greater than the specified value              |
| **Less Than**             | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY                  | Matches values that are less than the specified value                 |
| **Greater Than or Equal** | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY                  | Matches values that are greater than or equal to the specified value  |
| **Less Than or Equal**    | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY                  | Matches values that are less than or equal to the specified value     |
| **Range**                 | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY                  | Matches values within a specified range (between two values)          |
| **Starts With**           | STRING                                                                   | Matches string values that begin with the specified text              |
| **Ends With**             | STRING                                                                   | Matches string values that end with the specified text                |
| **Contains**              | STRING                                                                   | Matches string values that contain the specified text anywhere within |
| **Not Contains**          | STRING                                                                   | Matches string values that do not contain the specified text          |

#### Data type filter compatibility

**String filters:**

* `Equals`, `Not Equals`, `In`, `Starts With`, `Ends With`, `Contains`, `Not Contains`

**Numeric filters (INTEGER, FLOAT, CURRENCY):**

* `Equals`, `Greater Than`, `Less Than`, `Greater Than or Equal`, `Less Than or Equal`, `Range`

**Date filters (DATE\_TIME, ZONED\_DATE\_TIME):**

* `Equals`, `Not Equals`, `Greater Than`, `Less Than`, `Greater Than or Equal`, `Less Than or Equal`, `Range`

**Boolean filters:**

* `Equals`

**Enum filters:**

* `In`

<Tip>
  When using range filters, you'll need to specify both a minimum and maximum value. For date ranges, ensure the date format matches your system's configured format.
</Tip>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2017.07.35.png)
</Frame>

3. **Role-Specific Configurations**:
   * **Dataset Config** allows creating views tailored to specific audiences, such as different departments or roles within an organization. However, note that filters in Dataset Config do not override user permissions on task visibility.

Example with filter applied a number attribute:

<Frame>
  <video />
</Frame>

### Managing data model changes

Views are scoped to a process definition and do not need to be recreated when the data model changes. However, custom parameters used as columns must exist as keys in the process's data model before they can be added to Task Management. If you modify a custom key's attribute type after indexing, you must re-index it in **Process Settings** → **Task Management** for the change to take effect.

### Task details

The **Task Details** tab within **Task Manager** provides key process information, including:

* **Priority**: A numeric value (set via business rules) used for sorting and filtering tasks. Does not affect automatic allocation.
* **Status**: The current process instance status (for example, `STARTED`, `FINISHED`, or `ON_HOLD`).
* **Stage**: The current stage during process execution.
* **Comments**: User comments.
* **History**: Information such as task creation, creator, and status changes.
* **Last Updated**: Displays the most recent timestamp of any changes made to a task.
* **View Application**: Provides direct access to the container application URL where the FlowX.AI process related to a specific task is running.

<Frame>
  ![Task details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2017.46.01.png)
</Frame>

**Accessing Task details in Task Management**

To access the **Task Details** of a specific task in a Task Management view, follow these steps:

1. **Navigate to the Task Management Interface**:
   * Open the Task Management section within the project and select the desired **View** that contains the list of tasks.

2. **Locate the Task**:
   * In the selected view (e.g., All Tasks, Custom View), find the task you want to inspect. Use filters and sorting options if necessary to locate the task more efficiently.

3. **Open Task Details**:
   * Click on the task or select the **Details** option (often represented by an icon or “Details” link) associated with the task entry.
   * This action will open the **Task Details** panel, which provides an in-depth view of information specific to that task.

<Frame>
  <video />
</Frame>

<Info>
  Please note that specific roles must be defined in a process to utilize all the task management features. For configuration details, see [**Configuring Access Roles for Task Manager**](../../../../setup-guides/access-management/workspaces-access-rights).
</Info>

### Export and import views

You can export and import Task Management views to transfer them between projects or environments.

To import views:

1. Navigate to the **Views** list in Task Manager
2. Open the context menu and select **Import from Zip**
3. Select the ZIP file exported from another project or environment
4. If views with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting view (or use **Apply to all**):
   * **Keep both** - imports the view as a new copy alongside the existing one
   * **Replace** - overwrites the existing view with the imported version
   * **Skip this one** - keeps the existing view unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

## Process status updates

Task Manager displays the process instance status for each task. These statuses match the [process instance statuses](../../../projects/runtime/active-process/process-instance):

| Status                    | Definition                                                                                                                                                                                |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CREATED**               | Visible only if there is an error during process creation. If the process starts without errors, it transitions directly to `STARTED`.                                                    |
| **STARTED**               | The process instance is running.                                                                                                                                                          |
| **FINISHED**              | The process reached an end node and completed execution.                                                                                                                                  |
| **FINISHED\_WITH\_ERROR** | The process completed but encountered errors during execution.                                                                                                                            |
| **FAILED**                | A [CronJob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) expired before the process completed. For example, if a process must finish by a deadline and does not. |
| **EXPIRED**               | The `expiryTime` defined in the process definition elapsed. Configure this in **Process Settings** → **General** → **Expiry time**.                                                       |
| **ABORTED**               | A subprocess was aborted because the [token was moved backward](../../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) in the parent process.             |
| **DISMISSED**             | A user stopped a running subprocess.                                                                                                                                                      |
| **ON\_HOLD**              | The process is frozen, blocking further actions. A superuser can place a process on hold for clarification and later unfreeze it.                                                         |
| **TERMINATED**            | A termination request ended all active tokens in the process and its subprocesses.                                                                                                        |

## Swimlanes and Stages updates

Task Manager also tracks swimlane and stage changes:

### Swimlanes updates

| Status             | Definition                           |
| ------------------ | ------------------------------------ |
| **Swimlane Enter** | Marks token entering a new swimlane. |
| **Swimlane Exit**  | Indicates token exiting a swimlane.  |

### Stages updates

| Status          | Definition                        |
| --------------- | --------------------------------- |
| **Stage Enter** | Marks token entering a new stage. |
| **Stage Exit**  | Indicates token exiting a stage.  |

## Using the plugin

The Task Manager plugin offers a range of features tailored to different roles, including:

* [Swimlane permissions for Task Management](#swmlane-permissions-for-task-management)
* [Assigning and unassigning Tasks](#task-assignment-and-reassignment)
* [Hold/unhold tasks](#hold/unhold-tasks)
* [Adding comments](#adding-comments)
* [Viewing the application](#viewing-the-application)
* [Bulk updates (via Kafka)](#bulk-updates)

### Swimlane permissions for Task Management

To perform specific actions within Task Management at process level, you must configure swimlane permissions at the process settings level. Each swimlane (e.g., BackOffice, FrontOffice, Manager) should be assigned appropriate roles and permissions based on the responsibilities and access needs of each user group.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2012.44.21.png)
</Frame>

**Example permissions configuration**

Below are example configurations for swimlane permissions based on roles commonly used in a loan application approval process:

1. **BackOffice Swimlane**:
   * Role: `FLOWX_BACKOFFICE`
   * Permissions:
     * **Unhold**: Allows the user to resume tasks that have been put on hold.
     * **Execute**: Enables the user to perform task actions.
     * **Self Assign**: Permits users to assign tasks to themselves.
     * **View**: Grants viewing rights for tasks.
     * **Hold**: Allows tasks to be temporarily paused.

2. **Manager (Supervisor) Swimlane**:
   * Role: `FLOWX_MANAGER`
   * Permissions:
     * **Unhold**: Allows the user to resume tasks that have been put on hold.
     * **Execute**: Enables the user to perform task actions.
     * **Self Assign**: Permits users to assign tasks to themselves.
     * **View**: Grants viewing rights for tasks.
     * **Hold**: Allows tasks to be temporarily paused.

<Info>
  These permissions can be customized depending on each use case and organizational needs. Ensure that permissions are aligned with the roles' responsibilities within the workflow.
</Info>

### Task assignment and reassignment

Consider this scenario: you're the HR manager overseeing the onboarding process for new employees. To simplify this operation, you've opted to use the task manager plugin. This process consists of two key phases: the Initiation Stage and the Account Setup Stage, each requiring a designated team member.

The Initiation Stage has successfully concluded, marking the transition to the Account Setup Stage. At this juncture, it's essential to reassign the task, originally assigned to John Doe, to Jane Doe, a valuable member of the backoffice team.

<Frame>
  <video />
</Frame>

### Hold/unhold tasks

As a project manager overseeing various ongoing projects, you may need to temporarily pause one due to unforeseen circumstances. To manage this, you use the "On Hold" status.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-13%2013.48.35.gif)
</Frame>

### Adding comments

When handling on-hold projects, document the reasons, inform the team, and plan for resumption. This pause helps address issues and ensures a smoother project flow upon resuming. Never forget to add comments:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-13%20at%2013.53.07.png)
</Frame>

### Viewing the application

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2017.08.21.png)
</Frame>

Container App URL represents an URL or a configuration parameter used to redirect users directly to a specific FlowX process instance.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2015.02.09.png)
</Frame>

#### Process settings level

In the Process Definition settings, navigate to the **Task Management** tab and locate the **Container App URL** field. Here, paste the container application URL where the process is loaded, following this format:

```
{container app url}/process
```

**Example**:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2017.10.54.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-30%2017.16.10.gif)
</Frame>

<Tip>
  You can also use a predefined generic parameter as the URL: `${genericParameter}`.

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2017.13.56.png)

  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-13%20at%2017.08.12.png)
</Tip>

#### Process data level

If task.baseUrl is specified in the process parameters, it will be sent to the Task Manager to update the tasks accordingly.

```java theme={"system"}
output.put("task", {"baseUrl": "https://your_base_url"});
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/tsk_manager_base_url.png)
</Frame>

<Warning>
  The `baseURL` set in the process data (business rules) will override the `baseURL` set in the process definition settings.
</Warning>

## Task operations via Kafka

You can perform task operations programmatically by sending Kafka messages to the `ai.flowx.core.trigger.operation.v1` topic. This enables integration with external systems and automation of task management workflows.

### Required Kafka headers

| Header               | Required | Purpose                                                                                                                                                                                                                  |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Fx-Organization-Id` | ✅ Yes    | Organization UUID. Messages without it are rejected with `MissingKafkaHeaderException`                                                                                                                                   |
| `Fx-Workspace-Id`    | ✅ Yes    | UUID of the workspace where the process instance lives                                                                                                                                                                   |
| `jwt`                | ❌ No     | JWT token of the user (or service account) performing the operation. Sets the security and audit context when present; messages without it are still processed. Operation attribution comes from the `author` body field |
| `callbackTopic`      | ❌ No     | Topic to receive the operation result; omit for fire-and-forget                                                                                                                                                          |

For details on how to obtain these values, see [Finding Identifiers and Parameters](../../integrations/finding-identifiers-and-parameters).

### Available operation types

| Operation Type | Description                                           |
| -------------- | ----------------------------------------------------- |
| **ASSIGN**     | Assigns the task to a specified user                  |
| **UNASSIGN**   | Unassigns the task from the user                      |
| **HOLD**       | Places the task on hold, blocking further actions     |
| **UNHOLD**     | Removes the hold status, allowing the task to proceed |
| **TERMINATE**  | Terminates the instance of the process                |

#### Field descriptions

| Field                   | Type          | Required           | Description                                                            |
| ----------------------- | ------------- | ------------------ | ---------------------------------------------------------------------- |
| **operationType**       | String        | ✅ Yes              | The type of operation to perform (see available operation types table) |
| **processInstanceUuid** | String (UUID) | ✅ Yes              | The UUID of the process instance                                       |
| **swimlaneName**        | String        | ✅ Yes              | Name of the swimlane where the task resides                            |
| **owner**               | Object        | ✅ Yes (for ASSIGN) | User details for assignment operations                                 |
| **taskId**              | String        | ❌ No               | Unique identifier of the task (optional)                               |
| **swimlaneId**          | String (UUID) | ❌ No               | Unique identifier of the swimlane (optional)                           |
| **author**              | String        | ❌ No               | The user performing the operation (typically email or username)        |

#### Owner object structure

| Field         | Type    | Required | Description                           |
| ------------- | ------- | -------- | ------------------------------------- |
| **username**  | String  | ✅ Yes    | Username or email of the user         |
| **firstName** | String  | ❌ No     | First name of the user being assigned |
| **lastName**  | String  | ❌ No     | Last name of the user being assigned  |
| **enabled**   | Boolean | ❌ No     | Whether the user account is enabled   |

### Required parameters by operation

<Tabs>
  <Tab title="ASSIGN">
    **Minimal parameters required:**

    | Parameter           | Required                        |
    | ------------------- | ------------------------------- |
    | operationType       | ✅ Yes                           |
    | processInstanceUuid | ✅ Yes                           |
    | swimlaneName        | ✅ Yes                           |
    | owner.username      | ✅ Yes (only username is needed) |
    | taskId              | ❌ No                            |
    | swimlaneId          | ❌ No                            |
    | author              | ❌ No                            |

    **Example:**

    ```json theme={"system"}
    {
      "operationType": "ASSIGN",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default",
      "owner": {
        "username": "user@flowx.ai"
      }
    }
    ```
  </Tab>

  <Tab title="UNASSIGN">
    **Minimal parameters required:**

    | Parameter           | Required |
    | ------------------- | -------- |
    | operationType       | ✅ Yes    |
    | processInstanceUuid | ✅ Yes    |
    | swimlaneName        | ✅ Yes    |
    | taskId              | ❌ No     |
    | swimlaneId          | ❌ No     |
    | author              | ❌ No     |

    **Example:**

    ```json theme={"system"}
    {
      "operationType": "UNASSIGN",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default"
    }
    ```
  </Tab>

  <Tab title="HOLD / UNHOLD">
    **Minimal parameters required** - swimlane and owner fields are not needed.

    | Parameter           | Required |
    | ------------------- | -------- |
    | operationType       | ✅ Yes    |
    | taskId              | ✅ Yes    |
    | processInstanceUuid | ✅ Yes    |
    | swimlaneName        | ❌ No     |
    | swimlaneId          | ❌ No     |
    | owner               | ❌ No     |
    | author              | ✅ Yes    |

    **Example (HOLD):**

    ```json theme={"system"}
    {
      "operationType": "HOLD",
      "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "author": "admin@company.com"
    }
    ```

    **Example (UNHOLD):**

    ```json theme={"system"}
    {
      "operationType": "UNHOLD",
      "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "author": "admin@company.com"
    }
    ```
  </Tab>

  <Tab title="TERMINATE">
    **Minimal parameters required:**

    | Parameter           | Required |
    | ------------------- | -------- |
    | operationType       | ✅ Yes    |
    | processInstanceUuid | ✅ Yes    |

    **Example:**

    ```json theme={"system"}
    {
      "operationType": "TERMINATE",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223"
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Ensure that users performing operations have the appropriate swimlane permissions configured in the process settings. Operations will fail if the user lacks the necessary permissions for the specified swimlane.
</Warning>

## Bulk updates

Send bulk update requests via Kafka (using Process Engine) to perform multiple operations at once. Use the Kafka topic:

* Send the operations as an array to the topic configured in the Process Engine's `KAFKA_TOPIC_PROCESS_OPERATIONS_BULKIN` variable (default: `ai.flowx.core.trigger.operations.bulk.v1`). The engine consumes the message and runs each operation in the array. For more information, see the [Task Management plugin topics](../../../../setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-the-task-management-plugin).

Bulk requests use the same Kafka headers as single operations (see [Required Kafka headers](#required-kafka-headers)). Set `callbackTopic` to receive a per-operation result list with `SUCCESS`, `PARTIAL_ERROR`, or `ERROR` status.

Example of a bulk request:

```json theme={"system"}
{
  "operations": [
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default",
      "owner": null,
      "author": "john.doe@flowx.ai",
      "requestID": "1234567891"
    },
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default",
      "owner": null,
      "author": "john.doe@flowx.ai",
      "requestID": "1234567890"
    }
  ]
}
```

For more information on bulk updates configuration, see FlowX Engine setup:

<Card title="FlowX Engine setup" href="../../../../setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-the-task-management-plugin" icon="file" />

## Updating Task Manager metadata through business rules

You can dynamically update task metadata during process execution using business rules. The engine intercepts values stored under the reserved `task` key in the process data and forwards them to Task Management.

### Reserved `task.*` keys

The following keys are reserved. When set via `output.put("task", {...})` in a business rule, the engine extracts them and sends them to Task Management:

| Key                    | Type   | Description                                                                                  |
| ---------------------- | ------ | -------------------------------------------------------------------------------------------- |
| `task.title`           | String | Display title shown in task lists and details                                                |
| `task.priority`        | Number | Numeric priority for sorting and filtering (does not affect automatic allocation)            |
| `task.baseUrl`         | String | Container app URL for the "View Application" link. Overrides the URL set in process settings |
| `task.tags`            | List   | Tags attached to the task                                                                    |
| `task.metadata`        | Object | Arbitrary metadata attached to the task                                                      |
| `task.businessFilters` | Object | Business filter values used for allocation and view filtering                                |
| `task.candidateUsers`  | List   | Candidate users for task assignment, overriding swimlane-level allocation settings           |

<Warning>
  The `task` key is **reserved**. Any data stored under `task.*` in process parameters is intercepted by the engine and sent to Task Management. Do not use the `task` key for other business data.
</Warning>

### Updating task title and priority

Here is how to update both the title and priority:

```javascript theme={"system"}
// Define your task title
taskTitle = "SME Branch Lending";
taskPriority = 1; 

// Update the task title
output.put("task", {
    "title": taskTitle,
    "priority": taskPriority
});
```

### Setting dynamic value based on business logic

You can set priority dynamically based on business conditions:

```javascript theme={"system"}
// Get client data and loan amount
const clientDataSection = input.clientDataSection;
const loanAmount = input.loanAmount;

// Create a descriptive task title
const taskTitle = `Loan Application # ${clientDataSection.firstName} - ${clientDataSection.lastName}`;

// Set priority based on loan amount
let taskPriority;
if (loanAmount > 50000) {
    taskPriority = 1; // HIGH priority for large loans
} else if (loanAmount > 10000) {
    taskPriority = 2; // MEDIUM priority for medium loans
} else {
    taskPriority = 3; // LOW priority for small loans
}

// Update both title and priority
output.put("task", {
    "title": taskTitle,
    "priority": taskPriority
});
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/task_and_title.png)
</Frame>

You can make task titles more dynamic and informative by incorporating process data:

```javascript theme={"system"}
// Get relevant data from the process
const clientName = input.get("customer.fullName");
const applicationId = input.get("application.id");
const loanAmount = input.get("loan.amount");

// Create a descriptive task title
const taskTitle = `Loan Application #${applicationId} - ${clientName} - ${loanAmount}`;

// Update the task title
output.put("task", {
    "title": taskTitle
});
```

## Full-Code implementation

For more customized UX, the **full-code** implementation using the **Task Management SDKs (React and Angular)** allows developers to build custom tables, cards, or any other UI elements based on the views and columns configured in Task Management.

## FAQs

<AccordionGroup>
  <Accordion title="What happens to currencies, numbers, and dates already indexed when a locale or format override is applied in the UI Designer?">
    A: The format changes will only affect how the data is displayed, not how it's indexed.
  </Accordion>

  <Accordion title="Can I switch to full-code if I'm not satisfied with the current view and filter options?">
    A: Yes, you can always switch to full-code and create custom views or tables using the Task Management SDK.
  </Accordion>

  <Accordion title="How are subprocess keys handled in Task Management?">
    A: To use data from a subprocess, you must send it to the parent process first. Subprocess keys are currently displayed in the task manager once indexed through the parent process.
  </Accordion>
</AccordionGroup>


# Using allocation rules
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/using-allocation-rules

Allocation rules automatically assign tasks to users as tokens enter a swimlane, distributing work based on each user's current task count.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2012.54.21.png)
</Frame>

Allocation rules automatically assign tasks to users as a token enters a swimlane that has a specific role configured. For example, you can route front-office tasks to one group and back-office tasks to another.

### How allocation works

When a task reaches a swimlane with allocation rules configured, the system:

1. Identifies **candidate users** — either all users with execute permissions in that swimlane, or a specific list you define.
2. Counts each candidate's **currently assigned tasks** across all processes.
3. Assigns the task to the user with the **fewest assigned tasks** (lowest workload).
4. If two or more users have the same task count, one is selected **randomly**.

<Info>
  Allocation is based purely on task count. Task **priority** does not affect which user receives the task — it is a display and filtering field only.
</Info>

## Accessing allocation rules

To access the allocation rules, follow the next steps:

1. Open **FlowX Designer**.
2. Go to your **Application** and from the side menu, under **Task Management**, select the **Allocation rules** entry.

## Adding process and allocation rules

To add process and allocation rules, follow the next steps:

1. Click **Add process** button, in the top-right corner.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-14%2013.01.30.gif)
</Frame>

2. Select a [**process definition**](../../../building-blocks/process/process-definition) from the drop-down list.

3. Click **Add swimlane allocations button (+)** to add allocations.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.03.34.png)
</Frame>

<Info>
  If there are no users with execute rights in the swimlane you want to add (`hasExecute: false`), the following error message will be displayed:

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.06.00.png)
  </Frame>
</Info>

4. **Option 1**: Allocate all users with `execute rights`.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/allocate_execute_rights.png)
</Frame>

5. **Option 2**: Allocate only users you choose from the drop-down list. You can use the search function to filter users by name.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/allocate_execute_rights1.png)
</Frame>

6. Click **Save**.

<Info>
  Users with out-of-office status are skipped by automatic allocation. For more information, see the [out-of-office records documentation](using-out-of-office-records).
</Info>

## Editing allocation rules

To edit allocation rules, follow the next steps:

1. Click **Edit** button.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.14.12.png)
</Frame>

2. Change the allocation method.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/change_allocation_method.gif)
</Frame>

3. Click **Save**.

### Viewing allocation rules

The allocation rules list displays all the configured swimlanes grouped by process:

1. **Process** - the process definition name where the swimlanes were configured
2. **Swimlane** - the name of the swimlane
3. **Allocation** - applied allocation rules
4. **Edited at** - the last time when an allocation was edited
5. **Edited by** - the user who edited/created the allocation rules

## Exporting/importing process allocation rules

To copy process allocation rules and move them between different environments, you can use the export/import feature.

You can export process allocation rules as JSON files directly from the allocation rules list:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.17.51.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.19.39.png)
</Frame>

## Related resources

<CardGroup>
  <Card title="Task Management Overview" href="./task-management-overview" icon="list-check">
    Learn about Task Management features and configuration
  </Card>

  <Card title="Task Management Localization" href="./task-management-localization" icon="language">
    Localize Task Management UI in 34+ languages
  </Card>

  <Card title="Out of Office Records" href="./using-out-of-office-records" icon="calendar-xmark">
    Manage user availability for task allocation
  </Card>
</CardGroup>


# Using out of office records
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/using-out-of-office-records

The Out-of-office feature allows you to register users availability to perform a task. It can be allocated manually or automatically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/out_of_office_records.png)

<Info>
  Users with out-of-office status are excluded from the candidates for automatic task allocation list during the out-of-office period. For more information, see the [allocation rules documentation](./using-allocation-rules).
</Info>

## Accessing out-of-office records

To add out-of-office records, follow the next steps:

1. Open **FlowX Designer**.
2. From the side menu, under **Task Management,** select the **Out office entry**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/access_out_of_office.png)

## Adding out-of-office records

To add out-of-office records, follow the next steps:

1. Click **Add out-of-office** button, in the top-right corner.
2. Fill in the following mandatory details:
   * Assignee - user single select
   * Start Date (:exclamation:cannot be earlier than tomorrow)
   * End Date (:exclamation:cannot be earlier than tomorrow)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/add_out_of_office.png)

3. Click **Save**.

## Editing out-of-office records

To edit out-of-office records, follow the next steps:

1. Click **Edit** button.
2. Modify the dates (:exclamation:cannot be earlier than tomorrow).
3. Click **Save**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/edit_out_of_office.png)

## Deleting out-of-office records

To delete out-of-office records, follow the next steps:

1. From the **out-of-office list**, select a **record**.
2. Click **Delete** button. A pop-up message will be displayed: *"By deleting this out-of-office record, the user will become eligible to receive tasks in the selected period. Do you want to proceed?"*

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/delete_out_of_office.png)

<Warning>
  If you choose to delete an out-of-office record, the user is eligible to receive tasks allocation during the mentioned period. For more information, see the [automatic task allocation documentation](./using-allocation-rules).
</Warning>

3. Click **Yes, proceed** if you want to delete the record, click **Cancel** if you want to abort the deletion.

<Info>
  If the out-of-office period contains days selected in the past, the user cannot delete the record, the following message is displayed: *“You can’t delete this record because it already affected allocations in the past. Try to shorten the period, if it didn’t end.”*
</Info>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/cant_delete_ooo.png)

## Viewing out-of-office records

The out-of-office records list contains the following elements:

1. **User** - firstName, lastName, userName
2. **Start Date** - the date when the out-of-office period will be effective
3. **End Date** - the date when the out-of-office period will end
4. **Edited at** - the last time when an out-of-office record was edited
5. **Edited by** - the user who edited/created the out-of-office record

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/view_ooo.png)

<Info>
  The list is sorted in reverse chronological order by "edited at" `dateTime` (newest added on top).
</Info>

## Related resources

<CardGroup>
  <Card title="Task Management Overview" href="./task-management-overview" icon="list-check">
    Learn about Task Management features and configuration
  </Card>

  <Card title="Task Management Localization" href="./task-management-localization" icon="language">
    Localize Task Management UI in 34+ languages
  </Card>

  <Card title="Allocation Rules" href="./using-allocation-rules" icon="arrows-split-up-and-left">
    Configure automatic task allocation rules
  </Card>
</CardGroup>


# Using stages
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/using-stages

You can define specific stages during the execution of a process. Stages are configured on each node and they will be used to trigger an event when passing from one stage to another.

## Creating a new stage

To create a new stage, follow the next steps:

1. Open **FlowX Designer**.
2. Go to Task Manager and select **Stages**.
3. Click **New Stage.**
4. Fill in the required details.

![Create new stage](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/stages_add_new.png)

## Assigning a node to a stage

To assign a node to a stage, follow the next steps:

1. Open **FlowX Designer** and then select your **process**.
2. Choose the node you want to assign and select the **Node Config** tab.
3. Scroll down until you find the **Stage** field and click the dropdown button.
4. Choose the stage you want to assign.

![Node Assigning](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/stages_node_assigning.png)

## Export and import

You can export and import stages to transfer them between projects or environments.

### Exporting

1. Navigate to **Task Manager** > **Stages**
2. Open the context menu and select **Export**
3. The stages are downloaded as a ZIP file

### Importing

1. Navigate to **Task Manager** > **Stages**
2. Open the context menu and select **Import**
3. Select the ZIP file exported from another project or environment
4. If stages with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting stage (or use **Apply to all**):
   * **Keep both** - imports the stage as a new copy alongside the existing one
   * **Replace** - overwrites the existing stage with the imported version
   * **Skip this one** - keeps the existing stage unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

***

## Related resources

<CardGroup>
  <Card title="Task Management Overview" href="./task-management-overview" icon="list-check">
    Learn about Task Management features and configuration
  </Card>

  <Card title="Task Management Localization" href="./task-management-localization" icon="language">
    Localize stage names and Task Management UI in 34+ languages
  </Card>
</CardGroup>


# Building a connector
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/building-a-connector

Build custom connectors to integrate external systems with FlowX.AI as independently deployable microservices.

## Connector essentials

At its core, a connector acts as an anti-corruption layer. It manages interactions with external systems and crucial data transformations for integrations.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/connector_structure.png)

## Key functions

Connectors act as lightweight business logic layers, performing essential tasks:

1. **Data Transformation**: Ensure compatibility between different data formats, like date formats, value lists, and units.

2. **Information Enrichment:** Add non-critical integration information like flags and tracing GUIDs.

## Creating a connector

1. **Create a Kafka Consumer:** Follow [**this guide**](./creating-a-kafka-consumer) to configure a Kafka consumer for your Connector.

2. **Create a Kafka Producer:** Refer to [**this guide**](./creating-a-kafka-producer) for instructions on setting up a Kafka producer.

<Info>
  Adaptable Kafka settings can yield advantageous event-driven communication patterns. Fine-tuning partition counts and consumers based on load testing is crucial for optimal performance.
</Info>

### Design considerations

Efficient Connector design within an event-driven architecture demands:

* Load balancing solutions for varying communication types between the Connector and legacy systems.
* Custom implementations for request load balancing, Connector scaling, and more.

<Check>
  Incorporate all received Kafka headers in responses to ensure proper communication with the FlowX Engine.
</Check>

### Connector configuration sample

Here's a basic setup example for a connector:

* Configurations and examples for Kafka listeners and message senders.
* **OPTIONAL**: Activation examples for custom health checks.

[Sample available here](https://github.com/flowx-ai/quickstart-connector/tree/feature/easy-start)

Follow these steps and check the provided code snippets to effectively implement your custom FLOWX connector:

1. **Name Your Connector**: Choose a meaningful name for your connector service in the configuration file (`quickstart-connector/src/main/resources/config/application.yml`):

```yaml theme={"system"}
spring:
  application:
    name: easy-connector-name # TODO 1. Choose a meaningful name for your connector service.
  jackson:
    serialization:
      write_dates_as_timestamps: false
      fail-on-empty-beans: false
```

2. **Select Listening Topic:** Decide the primary topic for your connector to listen on ( you can do this at the following path → `quickstart-connector/src/main/resources/config/application-kafka.yml`):

<Check>
  If the connector needs to listen to multiple topics, ensure you add settings and configure a separate thread pool executor for each needed topic (refer to `KafkaConfiguration`, you can find it at `quickstart-connector/src/main/java/ai/flowx/quickstart/connector/config/KafkaConfiguration.java`).
</Check>

3. **Define Reply Topic**: Determine the reply topic, aligning with the Engine's topic pattern.

4. **Adjust Consumer Threads**: Modify consumer thread counts to match partition numbers.

```yaml theme={"system"}
kafka:
  consumer.threads: 3  # TODO 4. Adjust number of consumer threads. Make sure number of instances * number of threads = number of partitions per topic.
  auth-exception-retry-interval: 10
  topic:
    in: ai.flowx.easy-connector.in # TODO 2. Decide what topic should the connector listen on.
    out: ai.flowx.easy-connector.out # TODO 3. Decide what topic should the connector reply on (this topic name must match the topic pattern the Engine listens on).
```

5. **Define Incoming Data Format (DTO)**: Specify the structure for incoming and outgoing data using DTOs. This can be found at the path: `quickstart-connector/src/main/java/ai/flowx/quickstart/connector/dto/KafkaRequestMessageDTO.java`.

```java theme={"system"}
//Example for incoming DTO Format
package ai.flowx.quickstart.connector.dto;

import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

@Getter
@Setter
@ToString
public class KafkaRequestMessageDTO { // TODO 5. Define incoming DTO format.
    private String Id;
}
```

6. **Define Outgoing Data Format (DTO)**: Specify the structure for outgoing data at the following path → `quickstart-connector/src/main/java/ai/flowx/quickstart/connector/dto/KafkaResponseMessageDTO.java`.

```java theme={"system"}
// Example for Outgoing DTO Format
package ai.flowx.quickstart.connector.dto;

import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

@Getter
@Setter
@ToString
@Builder
public class KafkaResponseMessageDTO implements BaseApiResponseDTO { // TODO 6. Define outgoing DTO format.
    private String name;
    private String errorMessage;
}
```

7. **Implement Business Logic**: Develop logic for handling messages from the Engine and generating replies. Ensure to include the process instance UUID as a Kafka message key.

Optional Configuration Steps:

* **Health Checks:** Enable health checks for all utilized services in your setup.

```yaml theme={"system"}
management: # TODO optional: enable health check for all the services you use in case you add any
  health:
    kafka.enabled: false

```

Upon completion, your configuration files (`application.yaml` and `application-kafka.yaml`) should resemble the provided samples, adjusting settings according to your requirements:

```yaml theme={"system"}
logging:
  level:
    ROOT: INFO
    ai.flowx.quickstart.connector: INFO
    io.netty: INFO
    reactor.netty: INFO
    jdk.event.security: INFO
server:
  port: 8080
spring:
  application:
    name: easy-connector-name
  jackson:
    serialization:
      write_dates_as_timestamps: false
      fail-on-empty-beans: false
management: 
  health:
    kafka.enabled: false
spring.config.import: application-kafka.yml
logging.level.ROOT: DEBUG
logging.level.ai.flowx.quickstart.connector: DEBUG
```

And your Kafka configuration file (`application-kafka.yaml`) should look like this:

```yaml theme={"system"}
spring:
  kafka:
    bootstrap-servers: localhost:9092
    security.protocol: "PLAINTEXT"
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
      properties:
        interceptor:
          classes: io.opentracing.contrib.kafka.TracingProducerInterceptor
        message:
          max:
            bytes: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
        max:
          request:
            size: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
    consumer:
      group-id: kafka-connector-group
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      properties:
        interceptor:
          classes: io.opentracing.contrib.kafka.TracingConsumerInterceptor

kafka:
  consumer.threads: 3  
  auth-exception-retry-interval: 10
  topic:
    in: ai.flowx.easy-connector.in 
    out: ai.flowx.easy-connector.out 
spring:
  kafka:
    security.protocol: "SASL_PLAINTEXT"
    properties:
      sasl:
        mechanism: "OAUTHBEARER"
        jaas.config: "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required oauth.client.id=\"${KAFKA_OAUTH_CLIENT_ID:kafka}\" oauth.client.secret=\"${KAFKA_OAUTH_CLIENT_SECRET:kafka-secret}\"  oauth.token.endpoint.uri=\"${KAFKA_OAUTH_TOKEN_ENDPOINT_URI:kafka.auth.localhost}\" ;"
        login.callback.handler.class: io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler
```

## Setting up the connector locally

For detailed setup instructions, refer to the Setting Up FlowX.AI Quickstart Connector Readme:

<Card title="Readme file" href="https://github.com/flowx-ai/quickstart-connector/tree/feature/easy-start/docs" icon="files" />

Prerequisites:

* a terminal to clone the GitHub repository
* a code editor and IDE
* JDK version 17
* the Docker Desktop app
* an internet browser

## Integrating a connector in FlowX.AI Designer

To integrate and utilize the connector within FlowX.AI Designer, follow these steps:

1. **Process Designer Configuration**: Utilize the designated communication nodes within the [Process Designer](../../building-blocks/process/process):

* [**Send Message Task**](../../building-blocks/node/message-send-received-task-node#message-send-task): Transmit a message to a topic monitored by the connector. Make sure you choose **Kafka Send Action** type.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/connector_topic.png)
</Frame>

* [**Receive Message Task**](../../building-blocks/node/message-send-received-task-node#message-receive-task): Await a message from the connector on a topic monitored by the engine.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/connector_topic_out.png)
</Frame>

2. **Connector Operations**: The connector identifies and processes the incoming message.
3. **Handling Response**: Upon receiving a response, the connector serializes and deposits the message onto the specified OUT topic.
4. **Engine Processing**: The engine detects the new message, captures the entire content, and stores it within its variables based on the configured variable settings.

You can check another example of a more complex connector by checking the following repository:

<Card title="Currency Exchange Example Connector" href="https://github.com/flowx-ai/quickstart-connector/tree/example/currency-exchange" icon="link" />


# Consuming FlowX from external apps
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps

Choose the right integration pattern when calling FlowX from your own code — embed the UI with the SDKs, trigger processes via REST or webhooks, drive events through Kafka, or react to events downstream.

This guide is for developers who want to integrate FlowX with their **own application or backend** — for example, embedding a FlowX-driven UI inside a React app, triggering a FlowX process from a backend job, or reacting to FlowX events in a downstream system.

Pick the pattern that matches what you are trying to do. Each section links to the reference docs for setup details.

<Warning>
  **Do not poll renderer-internal runtime endpoints from your own code.**

  Endpoints under `/api/runtime/process/.../status` and `/api/runtime/process/.../data` exist for the FlowX renderers (React / React Native / Angular / iOS / Android SDKs) to refresh their own state. They are not part of the public integration surface and their contracts can change between releases without notice. If you need process state in your own app, use one of the patterns below instead.
</Warning>

***

## Choose your pattern

| If you want to…                                                              | Use this pattern                                                    | Why                                           |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------- |
| Show FlowX-driven screens inside your existing web or mobile app             | [Renderer SDK](#1-embed-the-flowx-ui-with-an-sdk)                   | Handles state, validation, UI updates for you |
| Start a FlowX process from your backend, a scheduled job, or another service | [Public REST API](#2-trigger-a-process-via-rest)                    | Stable, documented, public endpoints          |
| Start a FlowX process when an external system fires an HTTP callback         | [Incoming Webhook](#3-trigger-a-process-from-an-incoming-webhook)   | No backend code needed; FlowX exposes the URL |
| Start a FlowX process from an event your other services already publish      | [Kafka custom integration](#4-trigger-a-process-from-a-kafka-event) | Fits event-driven architectures               |
| React to FlowX activity from a downstream system                             | [Kafka events outbound](#5-react-to-flowx-events)                   | Decoupled, stream-based                       |

***

## 1. Embed the FlowX UI with an SDK

Use a renderer SDK to render FlowX-driven UI flows and process screens inside your app. The SDK manages session state, polling, and form lifecycle — you do not need to call runtime endpoints directly.

<CardGroup>
  <Card title="React Renderer" icon="react" href="/5.9/sdks/react-renderer">
    Embed FlowX flows in a React application
  </Card>

  <Card title="React Native Renderer" icon="react" href="/5.9/sdks/react-native-renderer">
    Embed FlowX flows in a React Native application
  </Card>

  <Card title="Angular Renderer" icon="angular" href="/5.9/sdks/angular-renderer">
    Embed FlowX flows in an Angular application
  </Card>

  <Card title="iOS Renderer" icon="apple" href="/5.9/sdks/ios-renderer">
    Embed FlowX flows in a native iOS app
  </Card>

  <Card title="Android Renderer" icon="android" href="/5.9/sdks/android-renderer">
    Embed FlowX flows in a native Android app
  </Card>
</CardGroup>

**Use this when:** the UI your end users see should be driven by FlowX (forms, screens, navigation, validation).

**Do not use this when:** you only need a backend/server-to-server integration with no UI.

***

## 2. Trigger a process via REST

Start a process programmatically from any HTTP-capable code (backend service, CLI, scheduled job, partner system).

<Steps>
  <Step title="Get the build info">
    Call **[Get Build Info](/5.9/docs/api/start-process/get-build-info)** with the workspace ID and app ID to retrieve the active `buildId`. The active policy determines which build is currently live for the runtime.
  </Step>

  <Step title="Start the process">
    Call **[Start process by build id and process name](/5.9/docs/api/start-process/rest2)** with the `appId`, `buildId`, and process definition name. The response contains the new process instance UUID.

    For UI-action scenarios where the process should inherit a resource definition from a related instance, see [Start with resource definition and inherit values](/5.9/docs/api/start-process/start-process-rdi-inherit).
  </Step>

  <Step title="Locate the IDs you need">
    If you do not know your `workspaceId`, `appId`, or process definition name, see the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide.
  </Step>
</Steps>

**Use this when:** another service needs to kick off a FlowX process and the user-facing UI (if any) is handled separately.

**Do not use this when:** you are tempted to keep polling the runtime to track the process — switch to Kafka events or use the SDK instead.

***

## 3. Trigger a process from an incoming webhook

If the external system can call an HTTP endpoint, FlowX exposes a Webhook Gateway URL per resource definition. The system POSTs to the URL, FlowX starts the process. No code on your side beyond configuring the call.

<Card title="Incoming Webhooks" icon="webhook" href="./incoming-webhooks">
  Configure webhook-triggered processes, secure them with API keys
</Card>

**Use this when:** integrating with a third-party SaaS that supports outbound webhooks (Slack, GitHub, payment providers, custom apps).

**Do not use this when:** the calling system is your own backend that already speaks Kafka — pattern 4 is more efficient.

***

## 4. Trigger a process from a Kafka event

Build a custom integration (Connector microservice) that publishes to a Kafka topic the FlowX engine listens on, or wire an existing event stream into the engine through a topic naming convention.

<Card title="Custom integrations and Kafka topics" icon="message" href="./integrations-overview">
  Custom integrations overview, topic naming, Connector quickstart
</Card>

**Use this when:** your architecture is already event-driven and you want FlowX to react to events alongside other consumers.

***

## 5. React to FlowX events

Run a downstream service that consumes Kafka events emitted by the FlowX engine — for example, audit forwarding, metrics, or notifications.

See the [custom integrations overview](./integrations-overview) for topic naming and event types.

**Use this when:** you need to mirror or transform FlowX activity into another system without coupling it to a synchronous API call.

***

## Authentication

All public REST endpoints require a Bearer token issued by the configured identity provider (Keycloak by default). See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for setup, and the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide for retrieving the values you need to authenticate from outside the platform.

<Note>
  The reference pages linked above cover the most common public endpoints (build info + process start variants). FlowX exposes additional public endpoints — for example, starting workflows, fetching task views, and retrieving public data-model paths — that are not yet documented end-to-end. If you need one of those, contact the platform team and we will add it to the reference set.
</Note>

***

## Frequently asked

<AccordionGroup>
  <Accordion title="How do I know when a process I started has finished or what data it produced?">
    Do not poll runtime query endpoints from your own code. The supported approaches are:

    * If you need real-time process state in a UI, use a [Renderer SDK](#1-embed-the-flowx-ui-with-an-sdk) — it handles state for you.
    * If you need to react to completion in another service, consume the relevant Kafka event (see pattern 5).
    * If you need a callback to your own HTTP endpoint, model that as an explicit step in the process (a Service Task that calls your URL when the process reaches that node).
  </Accordion>

  <Accordion title="Can I build my entire UI in React without using the FlowX renderer?">
    You can, but you will not get FlowX's UI state management, validation, navigation, or form generation — those live inside the renderer. If you only need to start processes from a custom UI (not render FlowX-driven screens), pattern 2 is enough. If you need FlowX-driven screens, use the React Renderer.
  </Accordion>

  <Accordion title="Where do I find my appId and buildId?">
    See the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide. The `buildId` returned from [Get Build Info](/5.9/docs/api/start-process/get-build-info) is the one to use when starting a process from a frontend or external app.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Public REST API reference" icon="code" href="/5.9/docs/api/start-process/get-build-info">
    Endpoint specs for build info and starting processes
  </Card>

  <Card title="SDKs overview" icon="puzzle-piece" href="/5.9/sdks/sdks-overview">
    React, React Native, Angular, iOS, Android renderer SDKs
  </Card>

  <Card title="Incoming Webhooks" icon="webhook" href="./incoming-webhooks">
    Trigger processes from external HTTP callbacks
  </Card>

  <Card title="Custom integrations" icon="gears" href="./integrations-overview">
    Kafka-based Connectors and topic naming
  </Card>
</CardGroup>


# Creating a Kafka consumer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/creating-a-kafka-consumer

This guide focuses on creating a **Kafka** consumer using Spring Boot.

Here are some tips, including the required configurations and code samples, to help you implement a Kafka consumer in Java.

## Required dependencies

Ensure that you have the following dependencies in your project:

```xml theme={"system"}
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

<dependency>
    <groupId>io.strimzi</groupId>
    <artifactId>kafka-oauth-client</artifactId>
    <version>0.6.1</version>
</dependency>

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>2.5.1</version>
</dependency>

<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-kafka-client</artifactId>
    <version>0.1.13</version>
</dependency>
```

## Configuration

Ensure that you have the following configuration in your `application.yml` or `application.properties` file:

```yaml theme={"system"}
spring:
  kafka:
    bootstrap-servers: localhost:9092
    security.protocol: "PLAINTEXT"
    consumer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
      properties:
        max:
          partition:
            fetch:
              bytes: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB

kafka:
  consumer:
    group-id: 
    ...
    threads:
    ...
```

## Code sample for a Kafka Listener

Here's an example of a Kafka listener method:

```java theme={"system"}
@KafkaListener(topics = "TOPIC_NAME_HERE")
public void listen(ConsumerRecord<String, String> record) throws JsonProcessingException {

  SomeDTO request = objectMapper.readValue(record.value(), SomeDTO.class);

  // process received DTO
  // Make sure to replace *"TOPIC_NAME_HERE"* with the actual name of the Kafka topic you want to consume from. Additionally, ensure that you have the necessary serialization and deserialization logic based on your specific use case.
}
```


# Creating a Kafka producer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/creating-a-kafka-producer

This guide focuses on creating a **Kafka** producer using Spring Boot.

Here are some tips, including the required configurations and code samples, to help you implement a Kafka producer in Java.

## Required dependencies

Ensure that you have the following dependencies in your project:

```xml theme={"system"}
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

<dependency>
    <groupId>io.strimzi</groupId>
    <artifactId>kafka-oauth-client</artifactId>
    <version>0.6.1</version>
</dependency>

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>2.5.1</version>
</dependency>

<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-kafka-client</artifactId>
    <version>0.1.13</version>
</dependency>
```

## Configuration

Ensure that you have the following configuration in your `application.yml` or `application.properties` file:

```yaml theme={"system"}
spring:
  kafka:
    bootstrap-servers: localhost:9092
    security.protocol: "PLAINTEXT"
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      properties:
        message:
          max:
            bytes: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
        max:
          request:
            size: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
```

## Code sample for a Kafka producer

<Warning>
  Ensure that you have the necessary KafkaTemplate bean autowired in your producer class. The sendMessage method demonstrates how to send a message to a Kafka topic with the specified headers and payload. Make sure to include all the received Kafka headers in the response that is sent back to the **FlowX Engine**.
</Warning>

```java theme={"system"}
private final KafkaTemplate<String, Object> kafkaTemplate;

public void sendMessage(String topic, Headers headers, Object payload) {
  ProducerRecord<String, Object> producerRecord = new ProducerRecord<>(topic, payload);
  // make sure to send all the received headers back to the FlowX Engine
  headers.forEach(header -> producerRecord.headers().add(header));
  kafkaTemplate.send(producerRecord);
}
```

## Kafka headers

### Understanding Kafka headers in FlowX Integration

When integrating with FlowX Engine via Kafka, headers play a crucial role in message routing and processing. It's essential to preserve and include all received headers in responses back to the FlowX Engine.

<Info>
  **Need help finding identifier values?** Check out the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide to learn where to locate workspace IDs, application IDs, build IDs, process instance UUIDs, and other identifiers in FlowX Designer.
</Info>

### Important headers

| Header                                    | Purpose                                                              | Consequences If Missing                                                              |
| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `Fx-Organization-Id`                      | Organization UUID for the target deployment                          | **Message rejected** — consumers throw `MissingKafkaHeaderException` (non-retryable) |
| `Fx-Workspace-Id`                         | Identifies the workspace context for multi-tenant environments       | Workspace isolation may be compromised; data queries may fail                        |
| `jwt`                                     | JWT token for authenticated operations (process start, task actions) | Operations requiring user context will fail authorization                            |
| `fxContext`                               | Identifies the target process/subprocess in the hierarchy            | Messages may be incorrectly routed or not processed                                  |
| `Fx-AppId`                                | Identifies the application processing the message                    | Application context may be lost                                                      |
| `Fx-RootAppId`                            | Identifies the original application that initiated the process chain | Process origin tracking may be lost; important for complex process hierarchies       |
| `Fx-Build-App-Version-Id`                 | Contains the application version identifier for data querying        | Version-specific behaviors may be affected; data queries may fail                    |
| `processInstanceId`/`processInstanceUuid` | Primary keys for message correlation                                 | Message correlation may fail                                                         |
| `Fx-ProcessName`                          | Required for cross-process communication                             | "Start another process via Kafka" functionality may break                            |

### The Fx-Organization-Id header

All FlowX Kafka consumers validate the `Fx-Organization-Id` header on every incoming message. Messages without it are **rejected immediately** with a non-retryable `MissingKafkaHeaderException`.

Set this header to the Organization UUID for your deployment. In self-hosted deployments, this is the same `ORGANIZATION_ID` value configured on all services.

```java theme={"system"}
producerRecord.headers().add("Fx-Organization-Id",
    "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx".getBytes(StandardCharsets.UTF_8));
```

### The fxContext header explained

The `fxContext` header is particularly important for routing messages in architectures with embedded processes and subprocesses:

* For kafka-receive nodes in the root process: `fxContext = "main"`
* For an embedded subprocess with nodeId=4: `fxContext = "main:4"`
* For an embedded sub-subprocess with nodeId=12: `fxContext = "main:4:12"`

This hierarchical format ensures messages are delivered to their intended recipients within the process structure.

### Understanding Fx-RootAppId

The `Fx-RootAppId` header is used to track the originating application throughout the entire process chain. This is particularly important when:

* Multiple applications are involved in a workflow
* Processes spawn subprocesses across different components
* You need to trace a complete transaction back to its originating application

Unlike `Fx-AppId` which may change as a message passes through different components, `Fx-RootAppId` preserves the original initiator's identity.

### Best Practices

1. **Preserve All Headers**: Always include all received Kafka headers in responses to the FlowX Engine.
   ```java theme={"system"}
   headers.forEach(header -> producerRecord.headers().add(header));
   ```


# Custom Agent node
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/custom-agent-node

Create AI agents with advanced capabilities using MCP tools to execute complex tasks in Integration Designer workflows.

## Overview

The **Custom Agent Node** is a specialized Integration Designer workflow node that enables you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.

<Frame>
  ![Custom Agent Node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca1.png)
</Frame>

## Key features

* **Tool Access**: Connect to one or more MCP servers to provide tools to the AI agent
* **Reasoning & Acting**: Built-in ReAct (Reasoning and Acting) model for intelligent decision-making
* **Multi-Step Execution**: Agent can use multiple tools in sequence to accomplish complex tasks
* **Structured Responses**: Define expected response schemas for consistent output
* **Execution Tracking**: Monitor tool usage and agent reasoning in console logs

<Info>
  Custom Agent nodes automatically apply the ReAct (Reasoning and Acting) model, which enables the AI agent to think through problems, decide which tools to use, and take actions based on the results.
</Info>

## When to use custom agent nodes

Custom Agent nodes are ideal for scenarios where you need:

* **Dynamic Decision Making**: The agent determines which tools to use based on the task
* **External System Integration**: Access external APIs, databases, or services through MCP tools
* **Complex Multi-Step Operations**: Execute workflows that require multiple tool interactions
* **Autonomous Problem Solving**: Let the AI agent figure out how to accomplish a goal using available tools

### Example use cases

<AccordionGroup>
  <Accordion title="Customer Support Automation">
    Create an agent that can:

    * Look up customer information from a CRM system
    * Check order status from an order management system
    * Generate personalized responses based on the gathered data
    * Create support tickets if needed
  </Accordion>

  <Accordion title="Data Analysis & Reporting">
    Build an agent that:

    * Queries multiple databases for relevant data
    * Performs calculations and aggregations
    * Generates charts and visualizations
    * Produces formatted reports
  </Accordion>

  <Accordion title="Process Automation">
    Design an agent that:

    * Monitors external systems for events
    * Validates data across multiple sources
    * Triggers actions in integrated systems
    * Handles exceptions and error cases
  </Accordion>

  <Accordion title="Integration Orchestration">
    Implement an agent that:

    * Coordinates operations across multiple systems
    * Transforms data between different formats
    * Handles complex business logic
    * Manages transaction workflows
  </Accordion>
</AccordionGroup>

## Adding a Custom Agent node

To add a Custom Agent node to an Integration Designer workflow:

1. Open **Integration Designer** and navigate to your workflow
2. Click **Select Next Node** dropdown
3. Select **Custom Agent** from the available node types
4. Configure the node settings

<Frame>
  ![Add Custom Agent](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca2.png)
</Frame>

<Info>
  Custom Agent nodes are available in Integration Designer workflows, alongside other node types like REST Endpoint, Script, Condition, and Subworkflow nodes.
</Info>

<Tip>
  The Custom Agent node is specifically designed for Integration Designer workflows. For BPMN process workflows, use the **Start Integration Workflow** action to invoke workflows that contain Custom Agent nodes.
</Tip>

## Configuring a Custom Agent node

After adding a Custom Agent node to your Integration Designer workflow, configure it through the node configuration panel:

<ParamField type="string">
  The agent's role, tasks, and expected input/output. Sent to the LLM as the **System message** and **cached** between executions to reduce cost and latency, so `${variable}` placeholders are not allowed in this field — use **Context** for dynamic values.

  Describe:

  * The agent's role and the task it should accomplish
  * Specific requirements or constraints
  * Expected output format and edge-case handling

  **Example:**

  ```
  You are a customer order assistant. For each request, retrieve the
  customer's recent order history and summarize it as a JSON object
  with fields: customerId, totalOrders, totalValue, recentOrders.
  If the customer is not found, return an error explaining the
  customer ID is invalid.
  ```
</ParamField>

<ParamField type="string">
  The per-execution prompt text, located inside the **Background** section of the node configuration panel. Supports `${variable}` placeholders for values from process data. Sent to the LLM as the **User message** on every execution and is **not** cached.

  **Example:**

  ```
  Customer ID: ${application.customerId}
  Look back window: last 6 months
  ```

  The **Background** section also exposes the Knowledge Base selector and the **Use only referenced values as input** toggle. In Chat Driven workflows, it additionally contains the **Use conversation memory** toggle.
</ParamField>

<ParamField type="array">
  One or more MCP servers whose tools will be available to the AI agent.

  **Configuration:**

  * Select from locally defined MCP servers
  * Include MCP servers from dependency libraries
  * Multiple selections allowed

  <Info>
    Only enabled tools from the selected MCP servers will be available to the agent. Tools can be managed in the MCP server details page.
  </Info>
</ParamField>

<ParamField type="string">
  JSON Schema defining the expected structure of the agent's response.

  This ensures the agent returns data in a consistent, predictable format that can be easily processed by subsequent nodes.

  **Example Schema:**

  ```json theme={"system"}
  {
    "type": "object",
    "properties": {
      "customerInfo": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "email": { "type": "string" }
        }
      },
      "orderSummary": {
        "type": "object",
        "properties": {
          "totalOrders": { "type": "number" },
          "totalValue": { "type": "number" },
          "recentOrders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "orderId": { "type": "string" },
                "date": { "type": "string" },
                "total": { "type": "number" }
              }
            }
          }
        }
      }
    },
    "required": ["customerInfo", "orderSummary"]
  }
  ```
</ParamField>

<ParamField type="string">
  The key in the process data where the agent's response will be stored.

  **Example**: `agentResponse`, `customerData`, `analysisResults`

  If the key already exists in the process data, it will be overwritten with the agent's response.
</ParamField>

<Frame>
  ![Custom Agent AI Config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca3.png)
</Frame>

## How custom agent nodes execute

When a Custom Agent node is executed in an Integration Designer workflow, the following process occurs:

<Steps>
  <Step title="Initialization">
    The FlowX Engine sends the Instructions (as the System message), the Context (as the User message), and the available tools to the AI Service.
  </Step>

  <Step title="Reasoning">
    The AI agent analyzes the prompt and determines which tools it needs to use and in what order.
  </Step>

  <Step title="Tool Execution">
    The agent requests tool execution through the MCP server:

    * Agent provides input parameters based on its reasoning
    * MCP server executes the tool
    * Results are returned to the agent
  </Step>

  <Step title="Iteration">
    The agent evaluates the results and decides whether to:

    * Use additional tools to gather more information
    * Process the data and formulate a response
    * Handle any errors or unexpected results
  </Step>

  <Step title="Response Generation">
    Once the agent has all necessary information, it generates a structured response according to the defined schema.
  </Step>

  <Step title="Data Storage">
    The response is stored in the process data at the specified response key and the workflow continues.
  </Step>
</Steps>

<Info>
  The agent's reasoning process, tool invocations, and results are all logged in the console for debugging and monitoring purposes.
</Info>

## Monitoring agent execution

After running a workflow with a Custom Agent node, you can monitor its execution in the **Console Logs**:

### Node logs tab

The **Logs** tab displays:

* **Execution Status**: Success, failure, or in-progress
* **Duration**: Time taken to complete the node execution
* **Tool Usage Summary**: Quick overview of which tools are used during the execution
* **Standard Output**: Agent's final response

<Frame>
  ![Agent Node Logs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca5.png)
</Frame>

### Tools tab

<Info>
  The **Tools** tab is only displayed when MCP tools have been used during execution.
</Info>

For each tool invocation, you can see:

<ParamField type="string">
  The name of the tool that was invoked.
</ParamField>

<ParamField type="string">
  The AI agent's reasoning for using this tool - why it decided this tool was necessary and what it hoped to accomplish.

  **Example**: "I need to retrieve the customer's information from the CRM system to get their contact details and account status."
</ParamField>

<ParamField type="object">
  The parameters sent by the AI agent to the MCP tool.

  **Example**:

  ```json theme={"system"}
  {
    "customerId": "CUST-12345",
    "includeOrders": true
  }
  ```
</ParamField>

<ParamField type="object">
  The response received from the MCP tool for the AI agent to interpret.

  **Example**:

  ```json theme={"system"}
  {
    "customer": {
      "id": "CUST-12345",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "tier": "premium"
    },
    "orders": [
      {
        "orderId": "ORD-001",
        "date": "2025-03-15",
        "total": 299.99
      }
    ]
  }
  ```
</ParamField>

<Frame>
  ![Agent Tools Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca4.png)
</Frame>

### Workflow-level logs

If the Custom Agent node is part of a larger workflow, tool usage information is also displayed at the workflow level:

1. Navigate to the workflow instance in Console Logs
2. View the workflow's **Tools** tab for an aggregated view of all tool usage
3. Drill down into specific nodes to see detailed tool execution

## Best practices

### Writing effective Instructions

<Check>
  **Be Specific**: Clearly define what the agent should accomplish

  ```
  Good: "Retrieve customer order history for the last 6 months and calculate total spend"
  Avoid: "Get customer info"
  ```
</Check>

<Check>
  **Set Expectations**: Describe the expected output format

  ```
  "Return a summary with: customer name, total orders, and average order value"
  ```
</Check>

<Check>
  **Handle Edge Cases**: Include guidance for error scenarios

  ```
  "If the customer is not found, return an error message explaining that 
  the customer ID is invalid"
  ```
</Check>

<Warning>
  Don't put `${variable}` placeholders in Instructions — they're rejected by the form because Instructions is the cached System message. Put per-execution values in **Context** instead.
</Warning>

### Writing effective Context

<Check>
  **Pass per-request values via placeholders**: keep the dynamic surface area small and named

  ```
  "For customer ${application.customerId}, check pending orders 
  from the ${application.orderSystem} system"
  ```
</Check>

<Check>
  **Use "Use only referenced values as input"** to send just the placeholders you reference, instead of the entire node input — narrows the model's context window and reduces token cost.
</Check>

### Selecting MCP servers

<Check>
  **Relevance**: Only include MCP servers whose tools are relevant to the agent's task
</Check>

<Check>
  **Minimize Scope**: Fewer tools = faster decision-making and more predictable behavior
</Check>

<Check>
  **Tool Availability**: Ensure required tools are enabled in the MCP server configuration
</Check>

### Defining response schemas

<Check>
  **Match Use Case**: Design the schema to match downstream data requirements
</Check>

<Check>
  **Required Fields**: Mark essential fields as required in the schema
</Check>

<Check>
  **Type Safety**: Use appropriate JSON Schema types for validation
</Check>

<Check>
  **Documentation**: Add descriptions to schema properties for clarity
</Check>

## Prompt suggestions

When a Custom Agent node has **Send as chat reply** enabled, you can configure it to generate recommended follow-up prompts alongside its chat response. These appear as clickable suggestion chips in the chat UI, guiding users toward relevant next steps in the conversation.

### How it works

When prompt suggestions are enabled:

1. The agent generates both a text reply and a list of follow-up suggestions in a single response
2. Suggestions appear as clickable chips below the agent's reply in the chat UI
3. Clicking a suggestion sends its content as the user's next message, continuing the conversation
4. Suggestions are one-time use — they disappear after one is clicked

### Configuring prompt suggestions

Prompt suggestions are configured through a **satellite panel** that appears on the workflow canvas, connected to the Custom Agent node.

<Steps>
  <Step title="Enable Send as chat reply">
    In the Custom Agent node configuration, toggle **Send as chat reply** to **ON**. This is required for prompt suggestions to be available.
  </Step>

  <Step title="Enable prompt suggestions">
    Toggle **Prompt Suggestions** to **ON** in the Response section. A satellite panel appears on the canvas, connected to the Custom Agent node.
  </Step>

  <Step title="Configure the satellite panel">
    The satellite panel contains the following settings:

    <ParamField type="string">
      Instructions that guide the agent on what kind of follow-up prompts to generate.

      **Default:** `Generate contextual follow-up replies the user is most likely to take next. Focus on actionable next steps, not clarifying questions.`

      Supports `${paramName}` interpolation for dynamic values from the process data.
    </ParamField>

    <ParamField type="number">
      Maximum number of suggestions the agent should generate per reply.

      **Default:** `3` (range: 1-5)
    </ParamField>

    <ParamField type="number">
      Maximum character length for each suggestion label displayed in the chat UI.

      **Default:** `120` (range: 10-200)
    </ParamField>
  </Step>
</Steps>

<Frame>
  ![Prompt Suggestions satellite panel on a Custom Agent node in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/prompt_suggestions.png)
</Frame>

<Tip>
  The satellite panel is draggable on the canvas. Its position is saved automatically. When you move the parent Custom Agent node, the satellite moves with it.
</Tip>

### Response structure

When prompt suggestions are enabled, the response schema is auto-generated. The agent's output is stored at the configured response key as a structured object instead of a plain string:

```json theme={"system"}
{
  "reply": "The Pro plan costs $49/month and includes unlimited agents...",
  "suggestions": [
    {
      "label": "Compare all plans",
      "content": "Show me a detailed comparison of the Starter, Pro, and Enterprise plans."
    },
    {
      "label": "How do I upgrade?",
      "content": "What are the steps to upgrade my current account to the Pro plan?"
    }
  ]
}
```

| Field                   | Description                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `reply`                 | The agent's text response displayed in the chat                                                |
| `suggestions[].label`   | Short text displayed on the suggestion chip in the chat UI                                     |
| `suggestions[].content` | Full prompt sent to the agent when the user clicks the suggestion. If omitted, `label` is used |

<Info>
  When prompt suggestions are enabled, the response schema is managed automatically — you cannot edit it manually. Turning off prompt suggestions restores the standard editable response schema.
</Info>

### Chat behavior

* **Display**: Suggestions render as clickable chips below the agent's reply message
* **Click**: Clicking a chip displays the `label` as the user's message and sends the `content` to the agent as the next input
* **Memory**: The `content` (not the label) is stored in conversation memory for context continuity
* **Conversation restore**: When restoring a previous conversation, suggestion labels are shown for past user selections, but active suggestions on the last message are not re-displayed

***

## Limitations

| Constraint                           | Value | Details                                                                                                                                                                                                                                                         |
| ------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Maximum tool calls per execution** | `20`  | The agent can make up to 20 tool calls in a single workflow execution. If the limit is reached, the execution stops and returns the last available result. Configurable via the `AGENT_BUILDER_MAX_TOOL_CALLS` environment variable on the AI platform service. |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent Not Using Expected Tools">
    **Problem**: The agent doesn't use the tools you expected.

    **Possible Causes**:

    * Instructions don't clearly indicate the need for specific tools
    * Tools are disabled in the MCP server configuration
    * Agent found an alternative approach

    **Solutions**:

    * Review and refine the Instructions to be more specific about when each tool should be used
    * Check MCP server tool status (enabled/disabled)
    * Review agent reasoning in the Tools tab to understand its decision-making
  </Accordion>

  <Accordion title="Response Doesn't Match Schema">
    **Problem**: The agent's response doesn't conform to the defined schema.

    **Possible Causes**:

    * Schema is too restrictive or doesn't match the prompt
    * Tools return unexpected data structures
    * Agent encountered errors during execution

    **Solutions**:

    * Verify schema matches what the prompt asks for
    * Test tools independently to verify their outputs
    * Review error logs for execution issues
    * Adjust schema or prompt to align better
  </Accordion>

  <Accordion title="Agent Execution Times Out">
    **Problem**: The Custom Agent node takes too long to execute.

    **Possible Causes**:

    * Too many MCP servers/tools available
    * Complex multi-step operations
    * External systems responding slowly

    **Solutions**:

    * Limit MCP servers to only those needed
    * Break complex tasks into multiple simpler agent nodes
    * Optimize external system performance
    * Increase timeout configuration if appropriate
  </Accordion>

  <Accordion title="Tool Invocation Fails">
    **Problem**: A tool invocation fails during agent execution.

    **Possible Causes**:

    * MCP server connection issues
    * Invalid parameters sent by agent
    * Tool authentication or permission errors

    **Solutions**:

    * Test MCP server connection in Integration Designer
    * Review tool input schema and agent's input in the Tools tab
    * Verify authentication credentials for the MCP server
    * Check tool-specific error messages in console logs
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="MCP Integration Overview" href="./mcp-integration/mcp-integration-overview" icon="plug">
    Learn about MCP integration capabilities
  </Card>

  <Card title="MCP Data Sources" href="./mcp-integration/adding-mcp-data-source" icon="database">
    Add, configure, and manage MCP servers and tools
  </Card>

  <Card title="Integration Designer" href="./integration-designer" icon="workflow">
    Learn about Integration Designer workflows
  </Card>
</CardGroup>

## Related resources

<Card title="Start Integration Workflow" href="../../building-blocks/actions/start-integration-workflow" icon="link">
  Learn how to call Integration Designer workflows from BPMN processes
</Card>


# Email Sender
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/email-sender

Configure SMTP email connections as data sources to send emails directly from your FlowX.AI processes, including replies to received emails and new outbound messages.

<Tip>
  For Microsoft Outlook mailboxes, you can also use the [Microsoft Outlook](./microsoft-outlook-data-source) data source which connects via the MS Graph API and supports both reading and sending emails in a single data source.
</Tip>

## Overview

<Frame>
  ![Add Data Source - Email Sender](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_email_sender_selected.png)
</Frame>

Email Sender is a data source type in Integration Designer that provides SMTP connectivity for sending emails from FlowX.AI processes. Combined with the [Send Notification](../../building-blocks/actions/send-notification-action) action, it enables use cases such as:

* **Replying to incoming emails**: Continue email conversation threads started by an [Email Trigger](./email-trigger)
* **Sending outbound notifications**: Send emails directly from business processes
* **Customer communication**: Automated responses, confirmations, and follow-ups

<Info>
  Email Sender handles **outbound** SMTP connections for sending emails. For **inbound** IMAP connections that trigger processes when emails arrive, see [Email Trigger](./email-trigger).
</Info>

***

## How it works

<Steps>
  <Step title="Create an Email Sender data source">
    Configure an SMTP connection in Integration Designer with your mail server credentials.
  </Step>

  <Step title="Link to a notification template">
    Select the Email Sender in a notification template's **Email Sender** field.
  </Step>

  <Step title="Add a Send Notification action">
    Add a [Send Notification](../../building-blocks/actions/send-notification-action) action to a process node and select the notification template.
  </Step>

  <Step title="Send emails from your process">
    When the action executes, the email is sent directly through the configured SMTP server.
  </Step>
</Steps>

***

## Creating an Email Sender data source

### Prerequisites

Before configuring an Email Sender, ensure you have:

* Access to Integration Designer with appropriate permissions
* SMTP server credentials (host, port, username, password)

### Access Integration Designer

Navigate to **FlowX Designer** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources** and click the **+** button to open the **Add Data Source** dialog.

### Configuration fields

Select **Email Sender** from the **Select Data Source** dropdown. The dialog displays all configuration fields in a single view:

<ParamField type="select">
  The email protocol to use. Only **SMTP** is available for Email Sender data sources.
</ParamField>

<ParamField type="string">
  The hostname or IP address of your SMTP server.

  **Placeholder:** "Enter Server Host or a Configuration Parameter"

  **Examples:**

  * `smtp.gmail.com`
  * `smtp.office365.com`
  * `mail.yourcompany.com`

  <Tip>
    This field accepts configuration parameters. Use `${configParam}` syntax to reference environment-specific values.
  </Tip>
</ParamField>

<ParamField type="number">
  The port number for the SMTP connection. The default value updates automatically based on the SSL/TLS setting.

  | SSL/TLS | Default Port |
  | ------- | ------------ |
  | ON      | `587`        |
  | OFF     | `465`        |
</ParamField>

<ParamField type="string">
  The email account username or full email address used for authentication.

  **Placeholder:** "Enter Username or a Configuration Parameter"

  <Tip>
    This field accepts configuration parameters for environment-specific credentials.
  </Tip>
</ParamField>

<ParamField type="string">
  The password or app-specific password for the email account.

  **Placeholder:** "Enter Password or a Configuration Parameter"

  <Warning>
    For Gmail and other providers with two-factor authentication (2FA) enabled, you may need to generate an app-specific password.
  </Warning>

  <Tip>
    Store sensitive credentials in configuration parameters and reference them here using `${configParam}` syntax.
  </Tip>
</ParamField>

<ParamField type="boolean">
  Turn on secure connection using SSL/TLS encryption. **Recommended: on.**

  <Info>
    Toggling SSL/TLS updates the default port value automatically.
  </Info>
</ParamField>

### Test the connection

Click the **Test Connection** button to verify your settings before creating the data source:

| Result    | Message                          | Action                                |
| --------- | -------------------------------- | ------------------------------------- |
| ✅ Success | "Established connection"         | Proceed to set name and create        |
| ❌ Error   | "Failed to establish connection" | Check credentials and server settings |

<Info>
  When you click **Create**, another authentication test is performed. If the test fails, you'll be redirected to the **Authorization** tab with an error message, but the Email Sender will still be created.
</Info>

### Name and description

<ParamField type="string">
  A unique, descriptive name for the Email Sender.

  **Placeholder:** "Add a name"

  **Validation rules:**

  * Required field
  * Must be unique within the project
  * Only letters, numbers, and these characters allowed: `[]`, `()`, `.`, `_`, `-`
  * Minimum 3 characters, maximum 50 characters
  * Cannot be "Default Server" (this is a reserved name)

  <Warning>
    The name "Default Server" is reserved for the environment-level default SMTP connection and cannot be used. If entered, you will see the error: *"Default Server" is a reserved name and cannot be used.*
  </Warning>
</ParamField>

<ParamField type="string">
  Optional description explaining the purpose of this Email Sender.

  **Placeholder:** "Add a description"
</ParamField>

Click **Create** to save the Email Sender data source.

***

## Using with notification templates

After creating an Email Sender data source, you can link it to notification templates:

1. Open a notification template in **Notification Templates**
2. Set **Email Server** to **Predefined Email Connection**
3. In the **Email Sender** field, select your Email Sender data source (or leave as **Default Server** to use the environment-level default)

For more details, see [Managing notification templates](../core-extensions/content-management/notifications-plugin/managing-notification-templates).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection test fails">
    Common causes:

    * **Incorrect credentials**: Verify username and password
    * **Wrong port**: Use `587` for SMTP with SSL/TLS, `465` without
    * **Firewall**: Ensure outbound connections to the SMTP server are allowed
    * **2FA enabled**: Generate an app-specific password for the email account
  </Accordion>

  <Accordion title="Emails not being sent">
    Check:

    1. Is the Email Sender linked to a notification template?
    2. Is the notification template's **Email Server** set to **Predefined Email Connection**?
    3. Is the [Send Notification](../../building-blocks/actions/send-notification-action) action configured correctly on the process node?
    4. Review process instance logs for error details
  </Accordion>

  <Accordion title="'Default Server' name validation error">
    The name "Default Server" is reserved for the environment-level default connection. Choose a different name for your Email Sender data source.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Send Notification Action" icon="paper-plane" href="../../building-blocks/actions/send-notification-action">
    Configure the Send Notification action to send emails from process nodes
  </Card>

  <Card title="Email Trigger" icon="envelope-open-text" href="./email-trigger">
    Configure IMAP connections to trigger processes from incoming emails
  </Card>

  <Card title="Microsoft Outlook" icon="envelope" href="./microsoft-outlook-data-source">
    Connect to Outlook via MS Graph API for reading and sending emails
  </Card>

  <Card title="Notification Templates" icon="file-lines" href="../core-extensions/content-management/notifications-plugin/managing-notification-templates">
    Create and manage email and SMS notification templates
  </Card>

  <Card title="Integration Designer" icon="puzzle-piece" href="./integration-designer">
    Learn about data source types and integration workflows
  </Card>
</CardGroup>


# Email Trigger
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/email-trigger

Configure email-based process triggers to automatically start process instances when emails are received. Email Triggers connect to IMAP mail servers and monitor specific mailboxes to initiate workflows.

<Card>
  Email Trigger is a data source type that enables process instances to be automatically started when emails are received via IMAP, bringing event-driven automation to your email workflows.
</Card>

<Tip>
  For Microsoft Outlook mailboxes, you can also use the [Microsoft Outlook](./microsoft-outlook-data-source) data source which connects via the MS Graph API and supports both reading and sending emails in a single data source.
</Tip>

### Email Trigger vs Microsoft Outlook

|                      | Email Trigger + Email Sender                           | Microsoft Outlook                                                  |
| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
| **Protocol**         | IMAP (read) + SMTP (send)                              | MS Graph API                                                       |
| **Authentication**   | Username + password / app password                     | Azure AD (client credentials)                                      |
| **Read + Send**      | Two separate data sources                              | Single data source (Read & Send scope)                             |
| **Reply threading**  | Manual — requires `Message-ID` header forwarding       | Native — uses MS Graph message ID to maintain conversation threads |
| **Provider support** | Any IMAP/SMTP-compatible mail server                   | Microsoft 365 / Outlook only                                       |
| **Best for**         | Gmail, self-hosted mail servers, or mixed environments | Organizations using Microsoft 365                                  |

## Overview

Email Trigger is a data source type in Integration Designer that allows FlowX.AI processes to be triggered automatically when emails arrive in a monitored mailbox. This enables use cases such as:

* **Customer support automation**: Automatically create support tickets when emails arrive
* **Document processing**: Trigger document workflows when emails with attachments are received
* **Request handling**: Start approval processes based on incoming email requests
* **Notification workflows**: Process automated alerts from monitoring systems

***

## How it works

The Email Trigger system follows a straightforward flow:

<Steps>
  <Step title="Configure Email Connection">
    Set up an IMAP connection to your email server as a Data Source in Integration Designer.
  </Step>

  <Step title="Link to Message Start Event (Start Catch Message)">
    Connect the Email Trigger to a Message Start Event node in your process definition.
  </Step>

  <Step title="Activate the Trigger">
    Turn on monitoring from the Manage Triggers section in Runtime Settings.
  </Step>

  <Step title="Process Incoming Emails">
    When emails arrive, FlowX.AI automatically creates process instances with the email data.
  </Step>
</Steps>

<Warning>
  **Email Triggers process only new emails**

  An Email Trigger only processes emails that arrive **after the trigger is activated for the first time**. Existing emails in the mailbox — whether read or unread — are never picked up retroactively.

  This applies to **reactivation as well**: if you deactivate and then reactivate a trigger, only emails that arrive **after the reactivation** are processed. Anything that landed in the mailbox during the inactive period is ignored.

  For IMAP triggers, the email must also still be **unread** in the monitored folder when the trigger picks it up.
</Warning>

***

## Creating an email trigger data source

### Prerequisites

Before configuring an Email Trigger, ensure you have:

* Access to Integration Designer with appropriate permissions
* IMAP server credentials (host, port, username, password)
* Knowledge of the mailbox folder to monitor (defaults to `INBOX` if not specified)

### Step 1: Access Integration Designer

<Steps>
  <Step title="Navigate to Data Sources">
    Navigate to **FlowX Designer** → **Workspaces** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources**
  </Step>

  <Step title="Add a new data source">
    Click **Add New Data Source**
  </Step>

  <Step title="Select Email Trigger">
    Select **Email Trigger** as the data source type
  </Step>
</Steps>

<Frame>
  ![Select Email Trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/email_trigger_mock.png)
</Frame>

### Step 2: Configure connection settings

Configure the IMAP connection with the following fields:

<ParamField type="string">
  The email protocol to use. Currently only **IMAP** is supported.
</ParamField>

<ParamField type="string">
  The hostname or IP address of your IMAP server.

  **Examples:**

  * `imap.gmail.com`
  * `outlook.office365.com`
  * `mail.yourcompany.com`

  <Tip>
    This field accepts configuration parameters. Use `${configParam}` syntax to reference environment-specific values.
  </Tip>
</ParamField>

<ParamField type="number">
  The port number for the IMAP connection. The default value updates automatically based on the SSL/TLS setting.

  | SSL/TLS | Default Port |
  | ------- | ------------ |
  | ON      | `993`        |
  | OFF     | `143`        |
</ParamField>

<ParamField type="string">
  The email account username or full email address used for authentication.

  <Tip>
    This field accepts configuration parameters for environment-specific credentials.
  </Tip>
</ParamField>

<ParamField type="string">
  The password or app-specific password for the email account.

  <Warning>
    For Gmail and other providers with 2FA enabled, you may need to generate an app-specific password.
  </Warning>

  <Tip>
    Store sensitive credentials in configuration parameters and reference them here using `${configParam}` syntax.
  </Tip>
</ParamField>

<ParamField type="boolean">
  Turn on secure connection using SSL/TLS encryption. **Recommended: ON.**

  <Info>
    The SSL/TLS setting determines the default port value. Change this setting before adjusting the port.
  </Info>
</ParamField>

### Step 3: Test the connection

Click the **Test Connection** button to verify your settings:

| Result    | Message                          | Action                                |
| --------- | -------------------------------- | ------------------------------------- |
| ✅ Success | "Established connection"         | Proceed to save                       |
| ❌ Error   | "Failed to establish connection" | Check credentials and server settings |

<Info>
  When you click **Create**, another authentication test is performed. If the test fails, you'll be redirected to the **Authorization** tab with an error message, but the Email Trigger will still be created.
</Info>

### Step 4: Configure basic information

<ParamField type="string">
  A unique, descriptive name for the Email Trigger.

  **Validation rules:**

  * Required field
  * Must be unique within the project
  * Only letters, numbers, and these characters allowed: `[]`, `()`, `.`, `_`, `-`
  * Minimum 3 characters, maximum 50 characters
</ParamField>

<ParamField type="string">
  Optional description explaining the purpose of this Email Trigger.
</ParamField>

***

## Configuring email trigger settings

After creating the Email Trigger, configure monitoring and validation settings in the **Settings** tab.

### Filtering criteria

Define which emails should trigger processes:

<ParamField type="string">
  The mailbox folder to monitor for incoming emails.

  **Default:** `INBOX`

  **Examples:**

  * `INBOX`
  * `Support`
  * `Orders/New`

  <Tip>
    This field accepts configuration parameters for environment-specific folder names.
  </Tip>
</ParamField>

<Frame>
  ![Email Trigger Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/trigger_email_props.png)
</Frame>

### Trigger condition and attachment forwarding

Email Trigger validation uses a two-stage model:

1. **Start Process for** — which incoming emails should create a process instance.
2. **Save email attachments on process** — which attachments are forwarded into the process data.

If a trigger condition fails, the email is rejected and appears in the **Failed Triggers** section. If an attachment is filtered out by the forwarding mode, it is dropped silently and no Failed Trigger is recorded.

#### Start Process for

Select which incoming emails create a process instance.

<ParamField type="radio">
  Start the process for all emails received in the selected mailbox folder.
</ParamField>

<ParamField type="radio">
  Start the process only when the email has at least one attachment. Emails without attachments are rejected with cause **No attachments**.
</ParamField>

<ParamField type="radio">
  Start the process if at least one attachment matches the selected file types. The **Allowed File Types** multiselect activates. Emails without a matching attachment are rejected with cause **No matching file types**.

  Allowed types use the categories below.

  | Type     | Extensions                                       |
  | -------- | ------------------------------------------------ |
  | PDF      | `.pdf`                                           |
  | DOCUMENT | `.doc`, `.docx`, `.txt`                          |
  | IMAGE    | `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff`, `.gif` |
  | EXCEL    | `.xls`, `.xlsx`, `.csv`                          |
  | ZIP      | `.zip`                                           |
</ParamField>

#### Save email attachments on process

Select which attachments from the email are passed into the process.

<ParamField type="radio">
  Save all attachments from the email to the process instance.
</ParamField>

<ParamField type="radio">
  No files are forwarded. Only email metadata (subject, body, sender, headers) reaches the process. The **Maximum File Size** field is disabled.
</ParamField>

<ParamField type="radio">
  Save only attachments that match the selected file types. The **Forward File Types** multiselect activates. Non-matching attachments are dropped silently (no Failed Trigger entry).
</ParamField>

#### Limits

<ParamField type="number">
  Maximum number of attachments allowed per email. If exceeded, the email is rejected at the trigger level and appears in **Failed Triggers** with cause **File count exceeded**.

  Leave empty for no limit.
</ParamField>

<ParamField type="number">
  Maximum allowed size per attachment file, in megabytes. Applies across all forwarding strategies.

  **Maximum allowed value:** 25 MB

  Leave empty to apply no per-file size limit beyond the 25 MB hard cap.
</ParamField>

<Note>
  **Triggers migrated from an earlier deployment**

  When a deployment is upgraded, existing triggers are set to **All incoming emails** + **All attachments**. The `Allowed File Types` value is preserved on the trigger but no longer filters anything until you switch the trigger condition or forwarding mode to one of the file-type options. Reopen each trigger after the upgrade to confirm the new settings match your intent.
</Note>

<Tip>
  All fields in the Settings section accept configuration parameters, enabling environment-specific configurations.
</Tip>

### Polling interval

<Info>
  The Email Trigger polls for new emails every **30 seconds** by default. This interval can be configured at the environment level but is not user-configurable in the UI.
</Info>

***

## Connecting to a Message Start Event

To use the Email Trigger, connect it to a **Message Start Event** node in your process definition.

### Configuring the Message Start Event

<Steps>
  <Step title="Open your process definition">
    Open your process definition in the Process Designer.
  </Step>

  <Step title="Add a Message Start Event node">
    Add a **Message Start Event** node.
  </Step>

  <Step title="Configure the Process Trigger">
    In the node configuration, locate the **Process Trigger** section:
  </Step>
</Steps>

<ParamField type="select">
  Select the trigger type:

  * **Internal Throw Message** - Traditional message-based triggering
  * **Email Trigger** - Email-based triggering
  * **Incoming Webhook** - Webhook-based triggering (see the [Incoming Webhooks](./incoming-webhooks) data source)
</ParamField>

<ParamField type="select">
  Select the Email Trigger data source to use. Only Email Triggers created in the current project are available.

  <Info>
    Tooltip: "The email connection that will be triggered"
  </Info>
</ParamField>

<Frame>
  ![Message Start Event with Email Trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/trigger_email_trigger_type_process.png)
</Frame>

<Warning>
  To start monitoring, you must activate the trigger from **Manage Triggers** in **Runtime Settings**.

  <Frame>
    ![Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/et5.png)
  </Frame>
</Warning>

***

## Email data schema

When an email triggers a process, the following data structure is available in your process variables:

```json theme={"system"}
{
  "emailMessage": {
    "subject": "Support Request #12345",
    "dateTime": "2026-01-15T10:30:00Z",
    "sender": "customer@example.com",
    "replyTo": ["replies@example.com"],
    "body": "Email body content...",
    "fileAttachments": [
      {
        "filePath": "email-attachments/proc-123/invoice.pdf",
        "downloadPath": "/api/internal/files/uuid-456/download"
      }
    ],
    "headerParams": {
      "Message-ID": "<abc123@example.com>",
      ...
    }
  }
}
```

<Frame>
  ![Email data schema](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/et6.png)
</Frame>

### Schema fields

| Field                            | Type              | Description                                                                                                                                                                                           |
| -------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject`                        | string            | Email subject line                                                                                                                                                                                    |
| `dateTime`                       | string (ISO 8601) | Timestamp when email was received                                                                                                                                                                     |
| `sender`                         | string            | Sender's email address                                                                                                                                                                                |
| `replyTo`                        | array of strings  | Reply-To addresses from the email header. Use these when sending a reply via the [Email Sender](./email-sender) or [Send Notification Action](../../building-blocks/actions/send-notification-action) |
| `body`                           | string            | Email body content (plain text)                                                                                                                                                                       |
| `attachments`                    | array             | List of attachment metadata objects                                                                                                                                                                   |
| `fileAttachments[].filePath`     | string            | Storage path in Document Plugin                                                                                                                                                                       |
| `fileAttachments[].downloadPath` | string            | API path to download the file                                                                                                                                                                         |
| `headerParams.Message-ID`        | string            | Unique email message identifier                                                                                                                                                                       |

### Attachment handling

Email attachments are automatically:

1. **Uploaded** to the Document Plugin as temporary files
2. **Copied** to permanent storage linked to the process instance
3. **Referenced** in the `fileAttachments` array with download paths

<Warning>
  Attachment processing happens asynchronously. The file copy to permanent storage may complete after the process instance starts. If your process needs to access attachments immediately, consider adding a wait step. Upload retries on `InterruptedException` only — up to 3 attempts with exponential backoff totaling roughly 7 seconds. Other failures (network, document plugin errors) fail fast.
</Warning>

### Forwarding incoming attachments to a reply

The inbound `fileAttachments[]` shape (`filePath`, `downloadPath`) differs from the outbound shape expected by the [Send Notification action](../../building-blocks/actions/send-notification-action)'s **Attachments** field (`path`, `filename`).

To forward original attachments on a reply, transform `emailMessage.fileAttachments` into the Send Notification shape — typically in a Script node — and pass the result through a process variable:

```javascript theme={"system"}
const replyAttachments = emailMessage.fileAttachments.map(f => ({
  path: f.filePath,
  filename: f.filePath.substring(f.filePath.lastIndexOf('/') + 1)
}));
```

Reference the resulting variable (for example, `${replyAttachments}`) in the Send Notification action's **Attachments** field.

***

## Managing triggers at runtime

### Accessing Manage Triggers

Navigate to **Runtime Settings** → **Manage Email Triggers** to view and control all configured Email Triggers.

### Trigger list columns

| Column           | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| **State**        | Current status: `Active` or `Inactive`                        |
| **Trigger Type** | Always "Email Trigger" for email-based triggers               |
| **Event Name**   | The Email Trigger data source name                            |
| **Location**     | Dependency application name, or `Local` for the current build |

### Activation requirements

For an Email Trigger to appear in Manage Triggers:

1. ✅ Email Trigger must be created as a Data Source
2. ✅ Email Trigger must be added to a Message Start Event node
3. ✅ The process must be part of a build in the **Active Policy**

<Info>
  When the Active Policy changes, Email Triggers retain their previous state (Active/Inactive). If an Email Trigger is deleted from the latest build, it will be automatically deactivated.
</Info>

<Info>
  All Email Trigger configuration changes and runtime actions (activation, deactivation, trigger events) are recorded in the audit trail for compliance and debugging purposes.
</Info>

### Activating and deactivating triggers

Use the toggle in the **State** column to activate or deactivate monitoring:

* **Active**: The system monitors the mailbox and creates process instances for incoming emails
* **Inactive**: Monitoring is paused; no new process instances are created

***

## Testing with mock email content

When running a process from the build list, you can provide mock email content to simulate an incoming email trigger. This is useful for:

* Testing process logic before connecting to a live mailbox
* Verifying attachment handling and validation rules
* Debugging email-triggered workflows in development

### How to test with mock email

<Steps>
  <Step title="Open the start process dialog">
    Navigate to your process definition and click **Start Process**. If the process has a Message Start Event configured with an Email Trigger, the dialog displays a mock email form instead of the standard start parameters.
  </Step>

  <Step title="Fill in the mock email fields">
    Complete the form fields to simulate an incoming email:

    | Field            | Description                                                                                                                                                                                     |
    | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Subject**      | The email subject line                                                                                                                                                                          |
    | **Sender**       | The sender email address                                                                                                                                                                        |
    | **Datetime**     | When the email was "received" (defaults to the current date and time)                                                                                                                           |
    | **Body**         | The email body content                                                                                                                                                                          |
    | **Upload files** | Attach files to simulate email attachments. Accepted types: PDF, DOCUMENT (.doc, .docx, .txt), IMAGE (.png, .jpg, .jpeg, .tif, .tiff, .gif), EXCEL (.xls, .xlsx, .csv), ZIP (.zip), up to 25 MB |
    | **Theme**        | Select the theme to use for the process instance                                                                                                                                                |
  </Step>

  <Step title="Start the process">
    Click **Start Process** to create a process instance using the mock email data, just as if a real email had been received.
  </Step>
</Steps>

<Tip>
  Use mock testing to validate your process handles edge cases — emails without attachments, emails with multiple Reply-To addresses, or emails with large body content.
</Tip>

***

## Handling failed triggers

When emails fail validation or processing errors occur, they appear in the **Failed Triggers** section.

### Accessing Failed Triggers

Navigate to **Runtime Settings** → **Failed Triggers** to view failed email processing attempts.

### Failed Triggers list

| Column           | Description                                                                          |
| ---------------- | ------------------------------------------------------------------------------------ |
| **Timestamp**    | Date and time (localized)                                                            |
| **Trigger Type** | "Email Trigger"                                                                      |
| **Trigger Name** | The Email Trigger data source name                                                   |
| **Cause Type**   | Type of failure                                                                      |
| **Context**      | Additional info, e.g., "Sender: [customer@example.com](mailto:customer@example.com)" |

### Cause types

<Tabs>
  <Tab title="File type not permitted">
    **Message:** "The file `{filename}` could not be uploaded because it is not on the list of permitted file types."

    **Resolution:** Update the Allowed File Types in the Email Trigger settings, or ask the sender to use an accepted format.
  </Tab>

  <Tab title="File size exceeded">
    **Message:** "`{filename}` is too large. Maximum allowed: 25 MB"

    **Resolution:** The attachment exceeds the maximum file size limit. Ask the sender to reduce the file size or split into multiple emails.
  </Tab>

  <Tab title="File count exceeded">
    **Message:** "File limit exceeded. For this Email Trigger there is a limit of `{limit}` files per email."

    **Resolution:** The email contains more attachments than the trigger-level **Maximum File Count**. Ask the sender to split attachments across multiple emails, or raise the limit on the trigger.
  </Tab>

  <Tab title="No attachments">
    **Message:** "Email rejected: trigger requires emails with attachments, but none were found."

    **Resolution:** The trigger is configured to **Start Process for → Only emails with attachments**, but the incoming email had none. Ask the sender to include an attachment, or switch the trigger condition to **All incoming emails**.
  </Tab>

  <Tab title="No matching file types">
    **Message:** "Email rejected: no attachments matching the allowed file types `{types}` were found."

    **Resolution:** The trigger is configured to **Start Process for → Only emails with these attachment file types**, and none of the inbound attachments matched the **Allowed File Types** list. Ask the sender to use an accepted format or widen the allowed list.
  </Tab>

  <Tab title="Unable to connect to email server">
    **Message:** "We couldn't connect to your email server. This might be due to:

    * Incorrect server settings
    * No internet connection
    * Firewall blocking the connection

    Please check your connection and try again."

    **Resolution:** Verify the IMAP server settings in the Email Trigger Authorization tab and test the connection.
  </Tab>
</Tabs>

### Failed trigger details page

Click on a failed trigger row to open the dedicated details page, which displays:

| Field                          | Description                                                             |
| ------------------------------ | ----------------------------------------------------------------------- |
| **Email Subject**              | Subject line of the failed email                                        |
| **Email Sender**               | Sender address                                                          |
| **Timestamp**                  | When the email was received                                             |
| **Cause Type**                 | Failure classification                                                  |
| **Error Details**              | Detailed error description, displayed in a code editor for easy reading |
| **Build Status**               | Whether the associated build is WIP or Committed                        |
| **Monitored Email Address**    | The email account being monitored                                       |
| **Monitored Inbox Folder**     | The mailbox folder being monitored                                      |
| **Process Definition**         | Link to navigate to the process definition (requires config rights)     |
| **Build**                      | Build identifier                                                        |
| **Project/Library**            | Source project or library                                               |
| **Build Created From**         | Branch name                                                             |
| **Project/Library Version ID** | Version identifier                                                      |

Use the breadcrumb navigation at the top of the page to return to the failed triggers list.

<Info>
  If an email fails for multiple reasons, all failure causes are listed in the details view.
</Info>

***

## Use cases

### Customer support ticket creation

<Steps>
  <Step title="Configure Email Trigger">
    Create an Email Trigger connected to your support email (e.g., `support@company.com`).
  </Step>

  <Step title="Design the process">
    Create a process that:

    * Extracts customer information from the email
    * Creates a ticket in your CRM
    * Assigns to the appropriate team
    * Sends an acknowledgment email
  </Step>

  <Step title="Handle attachments">
    Configure validation to accept relevant file types (PDF, images) and route attachments to your document management system.
  </Step>
</Steps>

### Document processing workflow

```
Email received with attachments
       ↓
Extract document metadata
       ↓
Classify document type (invoice, contract, etc.)
       ↓
Route to appropriate processing workflow
       ↓
Notify relevant stakeholders
```

***

## Best practices

<CardGroup>
  <Card title="Use Configuration Parameters" icon="gear">
    Store server credentials and environment-specific settings in configuration parameters for easy management across environments.
  </Card>

  <Card title="Set Appropriate Validations" icon="shield-check">
    Configure file type, size, and count limits to prevent processing of unwanted or malicious content.
  </Card>

  <Card title="Monitor Failed Triggers" icon="triangle-exclamation">
    Regularly review the Failed Triggers section to identify issues with email processing.
  </Card>

  <Card title="Handle Attachments Async" icon="clock">
    Remember that attachment processing is asynchronous. Design your process to handle potential delays in file availability.
  </Card>
</CardGroup>

<Warning>
  **Security Note:** Email attachments are uploaded without virus scanning in the current implementation. Consider implementing additional security measures for sensitive environments.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Email Trigger not appearing in Manage Triggers">
    Ensure all requirements are met:

    1. Email Trigger is created as a Data Source
    2. Email Trigger is linked to a Message Start Event
    3. The process is included in an Active Policy build
  </Accordion>

  <Accordion title="Connection test fails">
    Common causes:

    * **Incorrect credentials**: Verify username and password
    * **Wrong port**: Use 993 for IMAP with SSL/TLS
    * **Firewall**: Ensure outbound connections to the mail server are allowed
    * **2FA enabled**: Generate an app-specific password for the email account
  </Accordion>

  <Accordion title="Emails not triggering processes">
    Check:

    1. Is the trigger **Active** in Manage Triggers?
    2. Is the correct mailbox folder configured?
    3. Do incoming emails pass validation rules?
    4. Review Failed Triggers for error details
  </Accordion>

  <Accordion title="Attachments not available in process">
    Attachment processing is asynchronous. If you need immediate access:

    1. Add a wait step or message catch event after the start node
    2. Verify the email passed file validation rules
    3. Check Document Plugin connectivity
  </Accordion>
</AccordionGroup>

***

## Related documentation

<CardGroup>
  <Card title="Email Sender" icon="paper-plane" href="./email-sender">
    Configure SMTP connections to send and reply to emails from processes
  </Card>

  <Card title="Microsoft Outlook" icon="envelope" href="./microsoft-outlook-data-source">
    Connect to Outlook via MS Graph API for reading and sending emails
  </Card>

  <Card title="Send Notification Action" icon="envelope" href="../../building-blocks/actions/send-notification-action">
    Send emails and reply to received emails directly from process nodes
  </Card>

  <Card title="Integration Designer" icon="puzzle-piece" href="./integration-designer">
    Learn about other data source types and workflow creation
  </Card>

  <Card title="Message Start Event" icon="play" href="../../building-blocks/node/message-events/message-catch-start-event">
    Configure message-based process triggers
  </Card>

  <Card title="Document Plugin" icon="file" href="../core-extensions/content-management/documents-plugin/documents-plugin-overview">
    Manage files and attachments in FlowX.AI
  </Card>

  <Card title="Configuration Parameters" icon="sliders" href="../core-extensions/configuration-parameters">
    Use environment variables for flexible configurations
  </Card>
</CardGroup>


# File Storage
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/file-storage

Connect to external file storage (FTP, SFTP, S3, or Azure Blob) as a data source and move files in and out of FlowX from your workflows.

## Overview

File Storage is a data source type that lets you connect FlowX workflows to **external file storage your organization manages independently** — an FTP/SFTP server, an S3 (or S3-compatible) bucket, or an Azure Blob Storage container. You configure a connection, define named file operations against it, and call those operations from workflows.

<Note>
  Here, **external** means the storage is managed by your organization rather than by FlowX — it can still run entirely inside your own network. Point the **Host** at an in-cluster or on-prem FTP/SFTP server, or set the S3 **Endpoint URL** to a self-hosted MinIO bucket. FlowX provides the connector (`file-gateway`); you provide the storage.
</Note>

<CardGroup>
  <Card title="Connect to your storage" icon="folder-open">
    FTP, SFTP, S3 / S3-compatible, and Azure Blob Storage, each with its own connection and authorization settings
  </Card>

  <Card title="Define file operations" icon="list-check">
    Save named List, Download, Upload, Delete, and Move operations scoped to a root path
  </Card>

  <Card title="Browse and test" icon="flask">
    Browse files in the configured storage and run any operation live before you use it
  </Card>

  <Card title="Reusable in workflows" icon="diagram-project">
    Reference file operations from a Data Source node alongside other data sources
  </Card>
</CardGroup>

***

## Prerequisites

* An external file storage system reachable from your FlowX deployment: an FTP/SFTP server, an S3 or S3-compatible bucket (AWS S3, MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, and similar), or an Azure Blob Storage container.
* Credentials for the storage system with the permissions your operations require (read for List/Download, write for Upload/Move, delete for Delete).
* The **`file-gateway`** service deployed and able to reach both the storage system and the **`document-plugin`** service. See [File Gateway setup](/5.9/setup-guides/file-gateway-setup).

***

## Creating a File Storage data source

<Steps>
  <Step title="Open Data Sources">
    Navigate to **Integration Designer** → **Data Sources** in your project.
  </Step>

  <Step title="Add a new data source">
    Click the **+** button to open the **Add Data Source** dialog. In the **Files** category, select **External File Storage**.
  </Step>

  <Step title="Configure the connection on the Settings tab">
    New File Storage data sources open on the **Settings** tab, which has three sections:

    * **Protocol** — select the storage type: **FTP**, **SFTP**, **S3 / S3-compatible**, or **Azure Blob Storage**.
    * **Authorization** — choose an authorization type and supply credentials (see [Authorization](#authorization)).
    * **General Settings** — set the **Root Path** of the storage (all operations are scoped under this prefix) and the protocol-specific connection fields (see [Connection settings](#connection-settings)).
  </Step>

  <Step title="Test the connection">
    Click **Test connection** in the Authorization section to verify the credentials and connectivity. A successful test reports **Established connection**.
  </Step>

  <Step title="Save">
    Click **Save** to create the data source. Until a valid connection is saved, the **Files** tab shows *File storage is not configured* and the **Settings** tab shows a *Settings are not configured* warning.
  </Step>
</Steps>

***

## Connection settings

The connection fields depend on the protocol you select.

### FTP

| Field          | Description                                           | Default   |
| -------------- | ----------------------------------------------------- | --------- |
| **Host**       | FTP server hostname or IP (required)                  | —         |
| **Port**       | FTP port (required)                                   | `21`      |
| **Mode**       | Connection mode: **Active** or **Passive**            | `Passive` |
| **Encryption** | **None**, **FTPS (Explicit)**, or **FTPS (Implicit)** | `None`    |

### SFTP

| Field                        | Description                                                             | Default      |
| ---------------------------- | ----------------------------------------------------------------------- | ------------ |
| **Host**                     | SFTP server hostname or IP (required)                                   | —            |
| **Port**                     | SFTP port (required)                                                    | `22`         |
| **Strict host-key checking** | **Accept new** or **Require fingerprint**                               | `Accept new` |
| **Known-hosts fingerprint**  | Optional. The expected host-key fingerprint when requiring verification | —            |

### S3 / S3-compatible

| Field                 | Description                                                                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint URL**      | Optional. Leave blank for AWS S3. Set this only for S3-compatible stores (MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, Localstack, and similar).                                            |
| **Region**            | Required, including for non-AWS stores such as MinIO.                                                                                                                                                           |
| **Bucket**            | Required. Fixed for the lifetime of this data source.                                                                                                                                                           |
| **Path-style access** | Off by default (virtual-host style, the AWS default). Turn **ON** for path-style addressing, required by MinIO, Localstack, and most self-hosted stores. Rule of thumb: AWS S3 → off; MinIO / self-hosted → on. |

### Azure Blob Storage

| Field                    | Description                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| **Storage account name** | Required. The Azure storage account.                                    |
| **Container name**       | Required. The blob container.                                           |
| **Endpoint**             | Optional. A custom endpoint, when not using the default Azure endpoint. |

***

## Authorization

The available authorization types depend on the protocol:

| Protocol               | Authorization types                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **FTP**                | No authorization, or **Basic** (username / password)                                                                |
| **SFTP**               | **Basic** (username / password), or **Private key** (username + private key)                                        |
| **S3**                 | **Access key** (access key ID + secret access key)                                                                  |
| **Azure Blob Storage** | **Access key** (storage account name + account key), or **Service account** (tenant ID + client ID + client secret) |

For Azure with **Access key**, the credential fields are labeled **Storage Account Name** and **Account Key**.

***

## File operations

Each File Storage data source holds a list of named operations, managed on the **Operations** tab. Click to add an operation, choose its **Operation type**, and give it a **Name** and optional **Description**. Each operation opens a details page where you configure its parameters, and a test modal runs it live against the storage.

| Operation    | What it does                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **List**     | Lists file metadata inside the root path. Use **File Path** to target a subfolder and **File pattern** to filter results. |
| **Download** | Copies a file from external storage into Document Plugin internal storage for further processing.                         |
| **Upload**   | Copies a file from Document Plugin internal storage to external storage.                                                  |
| **Delete**   | Removes files from the external storage.                                                                                  |
| **Move**     | Moves a file within the external storage. Move can also rename the file.                                                  |

### Operation parameters

| Operation    | Parameters                                                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **List**     | **File Path** (optional subfolder), **File pattern** (optional wildcard, e.g. `*.csv`, `report-*.xml`, `2026/*.pdf`), **Recursive** toggle |
| **Download** | **Source File Path** (required), **Document folder** (required), **Document type** (optional), **File name override** (optional)           |
| **Upload**   | **Destination file path** (required), **Document plugin path** (required)                                                                  |
| **Delete**   | **File Path** (required)                                                                                                                   |
| **Move**     | **Source File Path** (required), **Destination path** (required)                                                                           |

<Note>
  Download and Upload exchange files with the **Document Plugin** internal storage rather than the workflow directly — Download brings an external file into FlowX, Upload sends a stored document out.
</Note>

### Browsing files

The **Files** tab is a file browser for the configured storage. Once a valid connection is saved, you can navigate the storage, copy file paths, and preview files. The browser is available only after the connection is configured on the Settings tab.

***

## Using in workflows

File operations are called from a **Data Source node** in workflows.

<Steps>
  <Step title="Add a Data Source node">
    On the workflow canvas, add a **Data Source** node and select your File Storage data source.
  </Step>

  <Step title="Select the operation">
    Pick one of the operations defined on that data source. The picker lists only the operations saved on the selected data source.
  </Step>

  <Step title="Map parameters">
    Map workflow inputs to the operation's parameters, and map the operation result (file list, document reference, or status) to a workflow variable.
  </Step>
</Steps>

***

## Deployment

File Storage operations run in the **`file-gateway`** service.

* **`file-gateway`** is MongoDB-backed and connects to the **`document-plugin`** service to exchange files; Download and Upload operations move files between external storage and document-plugin internal storage.
* It does **not** require Redis.
* It authenticates using the **`flowx-file-gateway-sa`** service account.
* The default maximum file size for operations is **1 GiB**.

For deployment configuration, see [File Gateway setup](/5.9/setup-guides/file-gateway-setup).

***

## Related resources

<CardGroup>
  <Card title="File Gateway setup" icon="gear" href="/5.9/setup-guides/file-gateway-setup">
    Deployment configuration for the file-gateway service
  </Card>

  <Card title="Integration Designer" icon="diagram-project" href="./integration-designer">
    Overview of all data source types and workflow building
  </Card>

  <Card title="Oracle Database" icon="database" href="./oracle-database">
    Connect to externally managed Oracle databases
  </Card>

  <Card title="Unmanaged MongoDB" icon="leaf" href="./unmanaged-mongodb">
    Connect to externally managed MongoDB instances
  </Card>
</CardGroup>


# Finding identifiers and parameters
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/finding-identifiers-and-parameters

A comprehensive reference guide for locating identifiers, UUIDs, and parameters required for API calls, Kafka integrations, and external system connections.

When integrating with FlowX APIs, configuring Kafka producers, or connecting external systems, you'll need various identifiers and parameters. This guide shows you exactly where to find each one in the FlowX Designer interface.

<Tip>
  **Quick tip**: Most UUIDs and identifiers in FlowX Designer can be copied by clicking the copy icon next to them or by right-clicking and selecting "Copy UUID" from the context menu.
</Tip>

## Common identifiers overview

<CardGroup>
  <Card title="Workspace ID" icon="building">
    Required for multi-tenant environments and data isolation
  </Card>

  <Card title="Project ID" icon="cube">
    Identifies your project in API calls
  </Card>

  <Card title="Build ID" icon="hammer">
    References a specific deployed version of your application
  </Card>

  <Card title="Process IDs" icon="diagram-project">
    Various identifiers for processes and their instances
  </Card>
</CardGroup>

## Organization identifiers

### Organization ID (Fx-Organization-Id)

The organization ID identifies the FlowX deployment tenant. It's mandatory on **every Kafka message** — messages missing this header are rejected with a non-retryable `MissingKafkaHeaderException`. On REST endpoints the header is read when present (to set security context) but not enforced.

<Steps>
  <Step title="Self-hosted (single-org) deployments">
    The organization ID is the value set in the `ORGANIZATION_ID` environment variable on all FlowX services. It is the UUID provided by FlowX when your organization is registered. See the [Organization Manager setup guide](../../../setup-guides/organization-manager-setup) for details.
  </Step>

  <Step title="From the Designer URL">
    After logging into the FlowX Designer, the organization ID appears in the URL path:

    ```
    https://designer.your-domain.flowx.ai/{organization-id}/...
    ```
  </Step>

  <Step title="From service configuration">
    Check the `ORGANIZATION_ID` environment variable on any FlowX service (process-engine, application-manager, etc.). All services share the same value in single-org deployments.
  </Step>
</Steps>

<Info>
  **Format**: UUID, for example `26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx`
</Info>

<Note>
  **Where it's used**:

  * Kafka header: `Fx-Organization-Id` (mandatory on every message)
  * REST header: `Fx-Organization-Id` (optional; read into security context if present)
  * Service config: `ORGANIZATION_ID` environment variable
  * CloudEvent extension: `flowxorganizationid`
</Note>

## Workspace identifiers

### Workspace ID (Fx-Workspace-Id)

The workspace ID is used to identify the workspace context in multi-tenant environments. It's required in certain Kafka headers and API calls.

<Steps>
  <Step title="Access Organization Settings">
    Navigate to **Organization Settings** from the main menu (available for organization admins and workspace admins).
  </Step>

  <Step title="Select Workspaces">
    Click on **Workspaces** in the left sidebar.
  </Step>

  <Step title="View Workspace List">
    You'll see all workspaces listed. Each workspace card displays:

    * Workspace name
    * Workspace UUID (this is your **Workspace ID**)
  </Step>

  <Step title="Copy the UUID">
    Click the contextual menu (three dots) and then select "Copy UUID" to copy the workspace UUID or copy it directly from the workspace URL when you're inside a workspace:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wid.png)
    </Frame>

    ```
    https://your-domain.flowx.ai/workspace/{workspace-id}/projects
    ```

    <Tip>
      The workspace ID is also visible in your browser's address bar when navigating within a workspace.
    </Tip>
  </Step>
</Steps>

<Info>
  **Default Workspace**: If you migrated from a pre-5.x version, your default workspace has the UUID: `00000000-0000-0000-0000-000000000001`
</Info>

<Note>
  **Where it's used**:

  * Kafka header: `Fx-Workspace-Id`
  * API calls requiring workspace context
  * Cross-workspace queries and data isolation
</Note>

## Project identifiers

### Global Application ID (globalId)

The global application ID is a unique identifier that enables cross-workspace application identification. This identifier remains constant for an application even when it's shared or referenced across different workspaces.

<Info>
  **Key characteristics**:

  * **Globally unique**: Unlike `appId` which is workspace-scoped, `globalId` uniquely identifies an application across all workspaces
  * **Cross-workspace operations**: Used internally for cross-workspace library sharing and application references
  * **Automatic assignment**: Generated automatically when an application is created
</Info>

<Note>
  **Where it's used**:

  * Internal cross-workspace application identification
  * Library sharing across workspaces
  * Cross-workspace data synchronization
</Note>

### Project ID (Fx-AppId, appId)

The project ID (also referred to as app ID) identifies your project within FlowX. It's one of the most commonly required identifiers.

<Steps>
  <Step title="Navigate to Projects">
    Go to your workspace and click on **Projects** in the main navigation.
  </Step>

  <Step title="Select Your Project">
    Click on the project you're working with to open it.
  </Step>

  <Step title="Copy from URL or Project Details">
    The project ID can be found in multiple places:

    **Option 1: From the URL**

    ```
    https://your-domain.flowx.ai/workspace/{workspace-id}/projects/{project-id}/...
    ```

    **Option 2: From Project Settings**

    * Click the three dots to access the contextual menu
    * Select "Copy UUID" to copy the project UUID

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prjid.png)
    </Frame>
  </Step>
</Steps>

<Note>
  **Where it's used**:

  * Kafka header: `Fx-AppId`
  * API path parameter: `/app/{appId}/...`
  * Process start requests
  * Runtime API calls
</Note>

### Root Application ID (Fx-RootAppId)

The root application ID tracks the originating application throughout process chains, especially when processes spawn subprocesses across different components.

<Tip>
  In most cases, `Fx-RootAppId` will be the same as `Fx-AppId` unless you're dealing with complex multi-application workflows.
</Tip>

<Note>
  **Where it's used**:

  * Kafka header: `Fx-RootAppId`
  * Tracking process chains across multiple applications
  * Subprocess communication
</Note>

## Build identifiers

### Build ID (buildId)

The build ID is a unique identifier for a specific committed version of your application that's been deployed to runtime.

<Steps>
  <Step title="Navigate to Runtime Builds">
    From your project, go to **Runtime → Builds**.
  </Step>

  <Step title="View Build List">
    You'll see all your builds listed with:

    * Build version number
    * Commit status
    * Creation date

    <Warning>
      **UI Limitation**: Currently, the build UUID is not displayed in the builds list, and there's no copy UUID button available. You can obtain the build ID through the [API](#obtaining-build-id-via-api) or from browser developer tools when viewing build details.
    </Warning>
  </Step>

  <Step title="Identify Active Build">
    <Info>
      **Active Policy**: The build marked as "Active Policy" is the one currently running in production. This is typically the build you'll want to use for API calls.
    </Info>
  </Step>
</Steps>

<Note>
  **Where it's used**:

  * API path parameter: `/build/{buildId}/...`
  * Runtime endpoints used by renderers
  * Version-specific API calls
</Note>

#### Obtaining Build ID via API

You can retrieve the build ID by calling the builds API endpoint:

```bash theme={"system"}
GET /appmanager/api/app/{appId}/builds
```

The response includes all builds with their `buildId` values.

### Application Version ID (appVersionId, Fx-Build-App-Version-Id)

The application version ID (also called `appVersionId` or `applicationVersionId`) identifies a specific app version. Unlike `buildId`, this identifier is **not unique by itself** - it's only unique when combined with `workspaceId`.

<Info>
  **Key distinction**:

  * **buildId**: Unique identifier for a committed build (globally unique)
  * **appVersionId**: Identifier for an app version (unique only within a workspace when combined with `workspaceId`)
  * **Kafka header `Fx-Build-App-Version-Id`** contains the `appVersionId`, NOT the `buildId`
</Info>

<Note>
  **Where it's used**:

  * API path parameter: `/app-version/{appVersionId}/...`
  * Kafka header: `Fx-Build-App-Version-Id` (replaces deprecated `Fx-BuildId`)
  * Internal Kafka communication between FlowX components
  * Always used in combination with `workspaceId` for unique identification
</Note>

<Info>
  **Technical note**: In API responses (e.g., `/api/app/{appId}/app-version/{appVersionId}`), you may see the app version ID duplicated in both the main response and within a `settings.applicationVersionId` field. This happens because the settings object represents a separate database table, and the view combines multiple tables without explicitly excluding the duplicate data.
</Info>

<Warning>
  **Deprecated Header**: `Fx-BuildId` is deprecated. Use `Fx-Build-App-Version-Id` instead. Note that this header contains the `appVersionId`, despite the "Build" in the header name.
</Warning>

## Process identifiers

### Process Definition Name (processDefinitionName)

The process definition name is the human-readable name you assigned when creating the process.

<Steps>
  <Step title="Navigate to Processes">
    From your project, go to **Definitions → Processes**.
  </Step>

  <Step title="View Process List">
    The process name is displayed prominently for each process in the list.
  </Step>

  <Step title="Copy Process Name">
    You can copy the exact process name by:

    * Selecting and copying the text directly
    * Opening the process and copying from the process settings
  </Step>
</Steps>

<Tip>
  Process names are case-sensitive and must match exactly when used in API calls or Kafka messages.
</Tip>

<Note>
  **Where it's used**:

  * API path parameter: `/process-name/{processDefinitionName}/start`
  * Kafka header: `Fx-ProcessName` (when starting a process via Kafka)
  * Process configuration and queries
</Note>

### Process Definition UUID

Process definitions have two types of UUIDs, each serving different purposes:

1. **Resource Definition ID** (`resourceDefinitionId`, `processDefinitionFlowxUuid`) - Permanent identifier
2. **Resource ID** (`resourceId`) - Version-specific identifier

<Info>
  **Critical distinction**:

  * **`resourceDefinitionId`** (also known as `processDefinitionFlowxUuid`): Stays **constant across ALL app versions**. This is the logical identifier for the process.
  * **`resourceId`**: Changes **with each app version** when the process is modified. This identifies a specific version of the process.
</Info>

#### Finding Process Definition UUID (resourceDefinitionId)

The `resourceDefinitionId` is the permanent identifier that stays the same across all versions. This is what you typically need for process references and integrations.

<Steps>
  <Step title="Open the Process">
    Navigate to **Definitions → Processes** and click on your process to open it.
  </Step>

  <Step title="Access Process Settings">
    Click the **Settings** icon (gear icon) in the process editor toolbar.
  </Step>

  <Step title="Copy UUID">
    The process UUID displayed in process settings is the `resourceDefinitionId`.

    <Warning>
      **UI Limitation**: Currently, there's no copy UUID button in the process list view. You need to open the process settings to access the UUID.
    </Warning>

    Alternatively, you can find it in the browser URL when editing a process:

    ```
    https://your-domain.flowx.ai/.../processes/{process-uuid}/edit
    ```
  </Step>
</Steps>

<Note>
  **Where it's used**:

  * Also referred to as `processDefinitionFlowxUuid` in some contexts
  * Process references and linking
  * Cross-version queries
  * Most integration scenarios (unless you specifically need a version-specific identifier)
</Note>

#### Finding Resource ID (version-specific)

The `resourceId` identifies a specific version of a process and changes with each app version.

<Info>
  **When you might need resourceId**: Typically, you won't need the version-specific `resourceId` unless you're working with internal APIs that specifically require it. Most integrations use `resourceDefinitionId` instead.
</Info>

<Note>
  **Where it's used**:

  * Version-specific API operations
  * Internal queries that need to target a specific app version
  * API responses (returned alongside `resourceDefinitionId`)
</Note>

### Resource Definition ID (resourceDefinitionId)

The resource definition ID is a **persistent identifier** for a resource that **stays the same across all app versions**. It's used to track the evolution of a resource through different versions and to link resources together.

<Info>
  **Key difference from resourceId**:

  * **resourceDefinitionId**: Permanent identifier that stays constant across versions. Use this to link resources together (e.g., a process using another process, a process using a workflow) and to track changes between different versions of the same resource.
  * **resourceId**: Version-specific identifier that changes with each app version. Use this when you need to modify or reference a specific version of a resource.
</Info>

<Info>
  **How to find it**: This ID is not directly visible in the FlowX Designer UI. It's returned in the response body when you make a GET request to fetch a specific resource by its resource ID.
</Info>

<Tabs>
  <Tab title="Via API Response">
    The `resourceDefinitionId` is present in every resource request (GET, update, delete). The URL pattern follows:

    ```
    /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/{resourceType}/ri/{resourceId}/...
    ```

    **Examples by resource type**:

    **Workflows**:

    ```bash theme={"system"}
    GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/workflow/ri/{resourceId}/integration/api/workflows/getById
    ```

    **Processes**:

    ```bash theme={"system"}
    GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/process/ri/{resourceId}/...
    ```

    The response includes the `resourceDefinitionId`:

    ```json theme={"system"}
    {
      "resourceId": "36ab1a35-fc4e-49ee-872d-b3551e3e33ce",
      "resourceDefinitionId": "e96fb0fb-a710-44db-b3bd-1a57bc2cb3e8",
      "applicationId": "fd44d9d9-b072-40fe-b12e-b7714105ba48",
      "name": "My Resource",
      ...
    }
    ```
  </Tab>

  <Tab title="Via List Endpoints">
    You can also find the `resourceDefinitionId` in the response when fetching lists of resources:

    **Get all workflows**:

    ```bash theme={"system"}
    GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/workflow/integration/api/workflows/all
    ```

    Each item in the response array will include its `resourceDefinitionId`.
  </Tab>

  <Tab title="Via Browser DevTools">
    1. Open FlowX Designer and navigate to your resource (process, workflow, etc.)
    2. Open browser developer tools (F12)
    3. Go to the **Network** tab
    4. Load or refresh the resource
    5. Find the GET request matching the pattern `/rt/{resourceType}/ri/{resourceId}/...`
    6. Check the response body for the `resourceDefinitionId` field

    <Tip>
      The GET request is usually the first call made when entering the details of a resource.
    </Tip>
  </Tab>
</Tabs>

<Note>
  **Where it's used**:

  * **Linking resources**: When one resource references another (process calls another process, process uses a workflow, etc.)
  * **Version tracking**: To track how a resource evolves across different app versions
  * **Cross-version queries**: Finding all versions of the same logical resource
  * **API responses**: Present in both individual resource requests and list endpoints

  **When to use resourceDefinitionId vs resourceId**:

  * Use `resourceDefinitionId` when you need to reference a resource logically, regardless of version
  * Use `resourceId` when you need to work with a specific version of a resource (editing, viewing, deploying)
</Note>

#### Understanding the relationship: A practical example

<Accordion title="Example: Process referencing a Workflow across versions" icon="diagram-project">
  Let's say you have:

  * **Process A** (Customer Onboarding)
  * **Workflow B** (Document Verification)

  **Scenario**: Process A needs to use Workflow B.

  **Version 1.0 (Initial):**

  ```json theme={"system"}
  {
    "workflowB": {
      "resourceId": "abc-123-v1",
      "resourceDefinitionId": "workflow-doc-verify"
    }
  }
  ```

  Process A references Workflow B using `resourceDefinitionId: "workflow-doc-verify"`

  **Version 2.0 (After modifying Workflow B):**

  ```json theme={"system"}
  {
    "workflowB": {
      "resourceId": "abc-456-v2",          // ⬅️ Changed
      "resourceDefinitionId": "workflow-doc-verify"  // ⬅️ Stays the same
    }
  }
  ```

  ✅ **The link still works** because Process A uses `resourceDefinitionId`, which remains constant.

  **Why this matters**:

  * When you modify Workflow B and create a new app version, its `resourceId` changes from `abc-123-v1` to `abc-456-v2`
  * But `resourceDefinitionId` stays `workflow-doc-verify`
  * Process A doesn't need to be updated because it references the logical resource, not a specific version
  * FlowX automatically resolves to the latest version of Workflow B in the active build

  **When modifying resources**:

  * Use `resourceId` in your API calls to edit/update/delete a specific version
  * Use `resourceDefinitionId` to understand which logical resource is being modified
  * Use `resourceDefinitionId` to track history: "Show me all versions of this workflow"
</Accordion>

### Process Instance UUID (processInstanceUuid)

When you start a process, FlowX creates a process instance with its own unique identifier.

<Steps>
  <Step title="Access Active Processes">
    Navigate to **Runtime → Active Process → Process instances**.
  </Step>

  <Step title="View Process Instances">
    You'll see a list of all running and completed process instances.
  </Step>

  <Step title="Open Process Status">
    Click on a process instance to view its details, then click the **Process Status** icon.
  </Step>

  <Step title="Copy Instance UUID">
    At the top of the process status view, you'll see:

    * **Active process instance**: The UUID of this specific process execution
    * Click the copy icon to copy the UUID
  </Step>
</Steps>

<Tip>
  **Where to find it programmatically**: Process instance UUIDs are returned in the response when you start a process via API. Store this value if you need to reference the instance later.
</Tip>

<Note>
  **Where it's used**:

  * Kafka header: `processInstanceUuid`
  * API calls to query or manipulate specific process instances
  * Correlation in Kafka messages
  * Audit log queries
</Note>

### Process Instance ID (processInstanceId)

In addition to the UUID, each process instance has a numeric ID.

<Steps>
  <Step title="View in Process Status">
    Open the process status (as described above for Process Instance UUID).
  </Step>

  <Step title="Check Instance Metadata">
    Scroll to the **Instance Metadata** section, which displays:

    * `processInstanceId`: The numeric ID
    * `processInstanceUuid`: The UUID
  </Step>
</Steps>

<Info>
  Both `processInstanceId` (numeric) and `processInstanceUuid` (UUID) identify the same process instance. **Prefer the UUID for integrations**: it's unique across all resource types, workspaces, and environments, and stays stable across data migrations or sequence resets. The numeric ID is only unique within a single database's sequence, so it can collide or shift when data moves between environments — use it for internal queries and legacy integrations.
</Info>

<Note>
  **Where it's used**:

  * Kafka header: `processInstanceId`
  * Internal database queries
  * Some legacy integrations
</Note>

## Token identifiers

### Token ID

Tokens represent the current position in a process flow. Each token has an identifier.

<Steps>
  <Step title="Open Process Status">
    Navigate to **Runtime → Active Process → Process instances** and open a process instance.
  </Step>

  <Step title="View Tokens Section">
    In the process status view, expand the **Tokens** section.
  </Step>

  <Step title="Identify Token">
    Each token displays:

    * Token ID (numeric)
    * Token state (ACTIVE, FINISHED, etc.)
    * Current node position
  </Step>
</Steps>

<Note>
  **Where it's used**:

  * Advanced process debugging
  * Custom integrations that need to track token movement
  * Internal FlowX Engine operations
</Note>

## Context and correlation identifiers

### fxContext

The `fxContext` header is crucial for routing messages in architectures with embedded processes and subprocesses.

<Info>
  **fxContext structure**:

  * Root process: `"main"`
  * Embedded subprocess (nodeId=4): `"main:4"`
  * Sub-subprocess (nodeId=12 inside subprocess 4): `"main:4:12"`
</Info>

<Warning>
  This value is automatically set by FlowX Engine when sending Kafka messages. You must preserve and return it unchanged in your responses.
</Warning>

<Note>
  **Where it's used**:

  * Kafka header: `fxContext`
  * Routing messages to specific subprocesses
  * Message correlation in complex process hierarchies
</Note>

## Authentication identifiers

### JWT Token

Most API calls and Kafka messages require authentication via JWT token.

<Steps>
  <Step title="Obtain from Browser (Development/Testing)">
    **For Development and Testing Only**:

    1. Log into FlowX Designer
    2. Open browser developer tools (F12)
    3. Go to the **Network** tab
    4. Make any request in FlowX Designer
    5. Click on the request and view headers
    6. Find the `Authorization` header and copy the JWT token (the part after "Bearer ")

    <Warning>
      Tokens obtained this way are temporary and tied to your user session. They will expire quickly and should only be used for development and testing purposes.
    </Warning>
  </Step>

  <Step title="Production Authentication">
    **For Production Integrations**:

    In production environments, external systems should authenticate using your configured Identity Provider (Keycloak or other OAuth2 provider) with appropriate user credentials or OAuth2 flows based on your security requirements.

    <Info>
      Work with your Customer Success team or security administrator to set up proper authentication flows for your production integrations. The authentication method will depend on your specific use case and security policies.
    </Info>
  </Step>
</Steps>

<Warning>
  **Security considerations**:

  * **Never hardcode JWT tokens** in your code. Tokens expire and should be refreshed regularly.
  * **Service accounts** (client credentials flow) have elevated privileges in FlowX and should be handled with extreme care.
  * **For self-hosted deployments**: Service account setup should be coordinated with your Customer Success team.
  * **For cloud deployments**: Contact FlowX support to discuss proper authentication strategies for your integration needs.
</Warning>

<Note>
  **Where it's used**:

  * HTTP header: `Authorization: Bearer {token}`
  * Kafka header: `jwt` (for process starts via Kafka)
  * All authenticated API calls
</Note>

## Quick reference table

Here's a quick lookup table for common identifiers:

| Identifier                     | Also Known As                                                     | Format | Where to Find                                       | Used In                     |
| ------------------------------ | ----------------------------------------------------------------- | ------ | --------------------------------------------------- | --------------------------- |
| Organization ID                | `Fx-Organization-Id`, `ORGANIZATION_ID`                           | UUID   | Service env var OR Designer URL path                | Kafka headers (mandatory)   |
| Workspace ID                   | `Fx-Workspace-Id`                                                 | UUID   | Organization Settings → Workspaces OR URL           | Kafka headers, API calls    |
| Global Application ID          | `globalId`                                                        | UUID   | API responses (internal)                            | Cross-workspace operations  |
| Project ID                     | `appId`, `Fx-AppId`                                               | UUID   | Project URL, Project Settings                       | API paths, Kafka headers    |
| Root Application ID            | `Fx-RootAppId`                                                    | UUID   | Same as Project ID (in most cases)                  | Kafka headers               |
| Build ID                       | `buildId`                                                         | UUID   | API: `/api/app/{appId}/builds`                      | Runtime API paths           |
| Application Version ID         | `appVersionId`, `applicationVersionId`, `Fx-Build-App-Version-Id` | UUID   | Runtime → Builds (not directly visible in UI)       | API paths, Kafka headers    |
| Process Definition Name        | `processDefinitionName`                                           | String | Definitions → Processes (process name)              | API paths, Kafka headers    |
| Process Definition UUID        | `processDefinitionFlowxUuid`, `resourceDefinitionId`              | UUID   | Process Settings OR URL when editing                | Process references, queries |
| Resource ID (version-specific) | `resourceId`, `rid`                                               | UUID   | API responses only                                  | Version-specific API ops    |
| Process Instance UUID          | `processInstanceUuid`                                             | UUID   | Runtime → Process Instances → Process Status        | Kafka headers, API calls    |
| Process Instance ID            | `processInstanceId`                                               | Number | Runtime → Process Instances → Instance Metadata     | Kafka headers               |
| Token ID                       | N/A                                                               | Number | Process Status → Tokens section                     | Advanced debugging          |
| fxContext                      | N/A                                                               | String | Automatically set by Engine (preserve in responses) | Kafka headers               |

<Info>
  **Important distinctions**:

  * **buildId** vs **appVersionId**:
    * `buildId` is globally unique and identifies a specific committed build
    * `appVersionId` is only unique when combined with `workspaceId`
    * The Kafka header `Fx-Build-App-Version-Id` contains `appVersionId`, NOT `buildId`
  * **resourceDefinitionId** vs **resourceId**:
    * `resourceDefinitionId` (also known as `processDefinitionFlowxUuid`): Stays constant across ALL app versions
    * `resourceId`: Changes with each app version when the process is modified
</Info>

## Common integration scenarios

### Starting a process via HTTP API

Required identifiers:

* **appId**: Project ID
* **buildId**: Build ID (obtained via API: `GET /appmanager/api/app/{appId}/builds`)
* **processDefinitionName**: Process name (from Definitions → Processes)
* **JWT token**: From authentication

```bash theme={"system"}
curl -X POST "https://your-domain.flowx.ai/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start" \
  -H "Authorization: Bearer {jwt-token}" \
  -H "Content-Type: application/json" \
  -H "flowx-platform: web" \
  -d '{"key": "value"}'
```

<Info>
  **Note**: The `buildId` is not directly visible in the FlowX Designer UI. Use the API endpoint mentioned above to retrieve it, or work with your Customer Success team to identify the correct build ID for your environment.
</Info>

### Starting a process via Kafka

Required Kafka headers:

* **Fx-Organization-Id**: Organization UUID (mandatory on every message)
* **Fx-Workspace-Id**: Workspace UUID
* **Fx-AppId**: Project ID
* **Fx-ProcessName**: Process definition name
* **jwt**: JWT token

```json theme={"system"}
{
  "headers": {
    "Fx-Organization-Id": "26ef7b5f-b463-4375-88c8-aaaaaaaaaaaa",
    "Fx-Workspace-Id": "00000000-0000-0000-0000-000000000001",
    "Fx-AppId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
    "Fx-ProcessName": "customer_onboarding",
    "jwt": "your-jwt-token"
  },
  "variables": {
    "customerName": "John Doe"
  }
}
```

### Responding to Kafka messages from FlowX

Required Kafka headers to preserve:

* **Fx-Organization-Id**: Organization UUID (mandatory on every response)
* **Fx-Workspace-Id**: Workspace ID
* **fxContext**: Process context (received from FlowX)
* **Fx-AppId**: Project ID
* **Fx-RootAppId**: Root application ID
* **Fx-Build-App-Version-Id**: Application version ID (contains `appVersionId`, used with `Fx-Workspace-Id` for unique identification)
* **processInstanceId**: Process instance numeric ID
* **processInstanceUuid**: Process instance UUID

```java theme={"system"}
public void sendMessage(String topic, Headers headers, Object payload) {
  ProducerRecord<String, Object> producerRecord = new ProducerRecord<>(topic, payload);
  // IMPORTANT: Preserve all received headers
  headers.forEach(header -> producerRecord.headers().add(header));
  kafkaTemplate.send(producerRecord);
}
```

<Warning>
  **Critical**: Always include ALL received Kafka headers when responding to FlowX Engine. Missing headers can cause message routing failures or data isolation issues.
</Warning>

<Info>
  **Backward compatibility**: You may still see the deprecated `Fx-BuildId` header in some messages. FlowX reads both `Fx-Build-App-Version-Id` (preferred) and `Fx-BuildId` (legacy) for backward compatibility. Always preserve both headers if present.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I can't find the workspace ID" icon="building">
    **Solution**: Make sure you have either **Organization Admin** or **Workspace Admin** permissions. Workspace IDs are visible in Organization Settings → Workspaces.

    If you can't access Organization Settings, ask your organization admin to provide the workspace ID or grant you appropriate permissions.
  </Accordion>

  <Accordion title="My API calls return 404 for build ID" icon="hammer">
    **Solution**: Ensure you're using the correct identifier for your API endpoint:

    1. **For `/build/{buildId}/...` endpoints**: You need the actual `buildId` which can be obtained via the API:
       ```bash theme={"system"}
       GET /appmanager/api/app/{appId}/builds
       ```
    2. **For `/app-version/{appVersionId}/...` endpoints**: Use the `appVersionId` (also referred to in the header as `Fx-Build-App-Version-Id`)
    3. Go to **Runtime → Builds** and verify the build status is "COMMITTED"
    4. Check if there's an **Active Policy** - this is usually the build you want to reference
    5. Note that the build UUID is not currently displayed in the UI - use the API endpoint above to retrieve it
  </Accordion>

  <Accordion title="Process won't start via Kafka" icon="message">
    **Common issues**:

    1. **Missing `Fx-Organization-Id` header**: Messages without this header are rejected immediately with a non-retryable `MissingKafkaHeaderException`. Verify the header is present and matches the `ORGANIZATION_ID` set on your FlowX services.
    2. **Missing or incorrect headers**: Verify `Fx-Workspace-Id`, `Fx-AppId`, `Fx-ProcessName`, and `jwt` headers
    3. **No active policy**: Check that the build is set as Active Policy in Runtime → Active Policy
    4. **Authentication failure**: Ensure the JWT token is valid and not expired
    5. **Process name mismatch**: Process names are case-sensitive - copy exact name from process list
    6. **Payload too large**: Ensure your Kafka message payload is under 1MB
  </Accordion>

  <Accordion title="Messages not routing to subprocess" icon="diagram-project">
    **Solution**: Check the `fxContext` header:

    * For subprocesses, `fxContext` must follow the hierarchical format
    * Example: `"main:4:12"` for a subprocess with nodeId=12 inside subprocess nodeId=4
    * Always preserve the exact `fxContext` received from FlowX Engine
    * Missing or incorrect `fxContext` causes messages to be delivered to the wrong process level
  </Accordion>

  <Accordion title="Can't find process instance UUID" icon="magnifying-glass">
    **Solution**:

    1. Navigate to **Runtime → Active Process → Process instances**
    2. Find your process instance by:
       * Process definition name
       * Start date/time
       * Current status
    3. Click to open process instance
    4. Click **Process Status** icon
    5. The UUID is shown at the top as "Active process instance"

    If you can't find it, check:

    * You're in the correct workspace
    * You have the correct project selected
    * The process might be in "Finished" status (use filters)
  </Accordion>
</AccordionGroup>

## Related documentation

<CardGroup>
  <Card title="Creating a Kafka Producer" icon="message" href="./creating-a-kafka-producer">
    Learn how to create Kafka producers and understand required headers
  </Card>

  <Card title="Workspaces" icon="building" href="../../projects/workspaces">
    Understand workspace concepts and multi-tenant architecture
  </Card>

  <Card title="Starting Processes" icon="play" href="../../flowx-designer/managing-a-project-flow/starting-a-process">
    Learn different methods for initiating process instances
  </Card>
</CardGroup>


# FlowX Database
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/flowx-database

Store and access structured data between processes and applications

## What is FlowX Database?

<Frame>
  <video />
</Frame>

FlowX Database (FlowX DB) is a persistence layer that allows you to store structured data independently of process instances. This enables you to:

* Share data between different process instances
* Store and retrieve data across multiple processes
* Create a persistent data store within the FlowX ecosystem
* Access structured data without directly interacting with external systems

<Info>
  FlowX Database is powered by the **nosql-db-runner** microservice, which provides MongoDB functionality within the FlowX ecosystem. This service supports both **native MongoDB** and **Azure Cosmos DB (MongoDB API)**, enabling you to choose the database backend that best fits your infrastructure needs while maintaining FlowX's workflow integration capabilities.

  For more information about the **nosql-db-runner** service and CosmosDB considerations, see the [NoSQL DB Runner documentation](../../../setup-guides/nosql-db-runner).
</Info>

## Key concepts

<Tabs>
  <Tab title="Collections">
    Collections are containers for storing documents in FlowX Database. Each collection:

    * Stores documents with similar structure
    * Has a unique identifier
    * Can be accessed from different processes
    * Functions similarly to a database table, but with more flexibility

    Collections are created and managed through the Data Sources section in the Integration Designer.
  </Tab>

  <Tab title="Operations">
    Operations define the actions you can perform on a collection. FlowX Database supports the full range of essential MongoDB operations:

    | Operation    | Description                                   | MongoDB Docs                                                                                           |
    | ------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
    | `find`       | Retrieve multiple documents based on criteria | [MongoDB find()](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/)             |
    | `findOne`    | Retrieve a single document                    | [MongoDB findOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.findOne/)       |
    | `insertOne`  | Add a single document                         | [MongoDB insertOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertOne/)   |
    | `insertMany` | Add multiple documents at once                | [MongoDB insertMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertMany/) |
    | `updateOne`  | Modify a single document                      | [MongoDB updateOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateOne/)   |
    | `updateMany` | Modify multiple documents at once             | [MongoDB updateMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateMany/) |
    | `deleteOne`  | Remove a single document                      | [MongoDB deleteOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteOne/)   |
    | `deleteMany` | Remove multiple documents at once             | [MongoDB deleteMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteMany/) |

    Each operation is configured with specific parameters that determine how it interacts with the data.
  </Tab>
</Tabs>

## Prerequisites

Before working with FlowX Database, you should have a solid understanding of:

<CardGroup>
  <Card title="MongoDB Fundamentals" icon="database">
    Basic knowledge of MongoDB operations, document structure, and query syntax
  </Card>

  <Card title="JSON Structure" icon="code">
    Understanding of JSON payloads and data formatting
  </Card>

  <Card title="CRUD Operations" icon="arrows-rotate">
    Familiarity with Create, Read, Update, and Delete operations in database systems
  </Card>

  <Card title="Query Modifiers" icon="filter">
    Knowledge of query parameters like filters, sorting, projection, and pagination
  </Card>
</CardGroup>

<Info>
  If you're new to MongoDB, we recommend reviewing the [MongoDB Manual](https://www.mongodb.com/docs/manual/) before working with FlowX Database operations.
</Info>

## Benefits of FlowX Database

<CardGroup>
  <Card title="Data Sharing" icon="share-nodes">
    Share data between different process instances, enabling more complex workflows and business scenarios
  </Card>

  <Card title="Independence" icon="unlock">
    Store data structured according to your needs, independent of external systems
  </Card>

  <Card title="Extended Use Cases" icon="expand">
    Enable new business cases that require persistent data across multiple processes
  </Card>

  <Card title="Simplified Integration" icon="puzzle-piece">
    Reduce the need for creating custom connectors to external systems for basic data persistence
  </Card>

  <Card title="Native Integration" icon="link">
    Integrate with workflows through the existing workflow designer
  </Card>

  <Card title="Complete CRUD Operations" icon="database">
    Perform all standard Create, Read, Update, and Delete operations on your data
  </Card>

  <Card title="Bulk Operations" icon="layer-group">
    Handle multiple documents efficiently with insertMany, updateMany, and deleteMany operations
  </Card>

  <Card title="Flexible Querying" icon="filter">
    Use MongoDB's query syntax to filter, sort, and project your data
  </Card>
</CardGroup>

## How to use FlowX Database

### Creating a collection

<Steps>
  <Step title="Access Data Sources">
    Navigate to the 'Integrations' section in the left sidebar of FlowX Designer, then click on 'Data Sources'.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db.png)
    </Frame>
  </Step>

  <Step title="Add a new Data Source">
    Click the "+" button to add a new Data Source. In the "Add Data Source" dialog, select "FlowX Database" from the dropdown list.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
    </Frame>
  </Step>

  <Step title="Configure the collection">
    Provide a name and description for your collection. The name will be used to identify this database collection in your workflows.

    <Warning>
      **Data Model Required**: You must have a data model defined before creating a FlowX Database collection. The data model becomes the schema for your database collection and defines the structure of documents that will be stored.
    </Warning>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb1.png)
    </Frame>

    * **Schema Definition**: Define the schema for your collection (the selected schema enhances auto-completion but does not enforce validation during insert or update)
    * **Partitioning Key**: The attribute used to partition data in your collection. By default, this is set to the `id` attribute, but you can specify a different field based on your data model.
  </Step>

  <Step title="Create the collection">
    Click "Create" to save the collection in FlowX Database. Your new collection will appear in the Data Sources list with the type "FlowX Database".
  </Step>
</Steps>

<Note>
  Each FlowX Database data source represents a collection in the underlying MongoDB database. When you create a new data source with the FlowX Database type, you're essentially creating a new collection where your documents will be stored.
</Note>

### Viewing collection data

<Steps>
  <Step title="Navigate to collection">
    Go to the collection you want to view in the 'Data Sources' section.
  </Step>

  <Step title="Access Documents tab">
    Click the 'Documents' section within the collection.
  </Step>

  <Step title="Browse documents">
    You'll see a listing of currently saved documents in the collection.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb2.png)
    </Frame>
  </Step>

  <Step title="Search and filter">
    Use the search functionality to find specific documents in the collection. You can add queries to filter documents, sort them, and use projections to choose what content from each entry you want to see.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb3.png)
    </Frame>

    <Info>
      FlowX Database currently relies on MongoDB’s native sorting behavior for query results.
      All sorting is performed using MongoDB’s default binary comparison rules.
    </Info>
  </Step>
</Steps>

### Managing collection settings

Each FlowX Database collection has a **Settings** tab where you can configure performance optimizations:

<Steps>
  <Step title="Access Settings tab">
    Navigate to your collection and click on the 'Settings' tab.
  </Step>

  <Step title="Define indexes">
    Create indexes for your collection to improve query performance. Indexes are particularly important for large collections as they significantly reduce query execution time.

    <Tip>
      Create indexes on fields that you frequently use in filter conditions, sort operations, or queries to optimize performance.
    </Tip>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb4.png)
    </Frame>
  </Step>
</Steps>

<Warning>
  Defining indexes in the Settings tab saves them as **configuration only** — they are not applied to the actual MongoDB collection immediately. To apply indexes, you must go to the **Runtime** view of your project or library, open the **Builds** section, and select **Apply Indexes** from the build's context menu. Only one build per project or library can have indexes applied at a time. Applying indexes on a new build will automatically replace any previously applied indexes that differ.

  For more details, see [Builds](/5.9/docs/projects/runtime/builds#apply-indexes).
</Warning>

<Info>
  For large collections with thousands of documents, proper indexing is crucial for maintaining good query performance. Consider indexing frequently queried fields before your collection grows large.
</Info>

### Creating database operations

<Tabs>
  <Tab title="Create operation">
    <Steps>
      <Step title="Access operations list">
        Navigate to your FlowX Database collection in the Data Sources section.
      </Step>

      <Step title="Create new operation">
        Click the "+" button to create a new operation.

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/new_operation.png)
        </Frame>
      </Step>

      <Step title="Select operation type">
        Choose the operation type from the dropdown (find, findOne, insertOne, insertMany, etc.).

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/operation_type_selection.png)
        </Frame>
      </Step>

      <Step title="Name the operation">
        Give your operation a meaningful name and description that indicates its purpose.
      </Step>

      <Step title="Define the operation parameters">
        Configure the parameters for your operation based on its type. For example, for a find operation:

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb5.png)
        </Frame>

        * **Filter**: Define the criteria to match documents
        * **Projection**: Select which fields to include in the results
        * **Sort**: Specify the sorting order
        * **Skip**: For find operations, specify the number of documents to skip
        * **Limit**: Set the maximum number of documents to return

        <Info>
          **Parameter Syntax**: When defining operation parameters, remember:

          * **Parameters defined in the operation** are referenced using `${parameterName}` syntax
          * **Database field names** must be in quotes (e.g., `"firstName"`, `"customerId"`)
          * Parameters don't need to match your data model exactly - they're placeholders that get replaced with actual values
          * Field names in quotes must match exactly what's stored in the database (same as your data model)
        </Info>
      </Step>

      <Step title="Test the operation">
        Use the test functionality to verify your operation works correctly.

        <Frame>
          ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb6.png)
        </Frame>

        <Warning>
          **Testing Delete Operations**: Be extremely careful when testing delete operations (`deleteOne` and `deleteMany`) as they will actually remove documents from your collection. Always use test data or ensure you have backups before testing deletion operations in collections with important data.
        </Warning>
      </Step>

      <Step title="Save the operation">
        Click "Save" to add the operation to your collection. It will now be available for use in workflows.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Update operation">
    <Steps>
      <Step title="Select operation">
        From the list of operations, select the one you want to update.
      </Step>

      <Step title="Make changes">
        Update the operation name, description, or parameters as needed.
      </Step>

      <Step title="Test updated operation">
        Test the updated operation to ensure it works as expected.
      </Step>

      <Step title="Save changes">
        Save your changes to apply them to the operation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Delete operation">
    <Steps>
      <Step title="Select operation">
        From the list of operations, select the one you want to delete.
      </Step>

      <Step title="Delete operation">
        Click the delete button and confirm the deletion when prompted.
      </Step>

      <Step title="Verify removal">
        Verify that the operation has been removed from the collection.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Visual query builder

Instead of writing raw MongoDB query syntax, you can use the visual query builder to define filters, updates, projections, and sorting through a guided interface that understands your collection's schema.

Each operation type has a tailored builder experience. You can switch between **Visual** and **Script** mode at any time using the mode toggle. The two modes work independently — saving in one mode sets that as the active query for the operation.

<Warning>
  Switching modes does not sync changes between them. A warning message informs you that saving in the current mode will set it as the final query for the operation.
</Warning>

#### Condition rows

The core building block of the query builder is the **condition row**, used in filter sections across all operation types:

| Element               | Description                                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Field dropdown**    | Pick a field from the collection schema. Supports nested paths (e.g., `address.city`). Shows a data type badge for each field.                                              |
| **Operator dropdown** | Type-aware operators that change based on the selected field's data type (see table below).                                                                                 |
| **Value input**       | Enter a static value or switch to dynamic mode using `${paramName}` syntax. Input type adapts to the field type (text, number, date picker, boolean toggle, enum dropdown). |
| **Remove button**     | Delete the condition row.                                                                                                                                                   |

Multiple condition rows can be combined with **AND** or **OR** logic using a dropdown selector. AND is the default.

#### Type-aware operators

The available operators change based on the selected field's data type:

| Field type    | Available operators                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| **String**    | equals, not equals, contains, starts with, ends with, regex, in, not in, exists, is null                   |
| **Number**    | equals, not equals, greater than, greater or equal, less than, less or equal, between, in, exists, is null |
| **Boolean**   | is true, is false, exists                                                                                  |
| **Date/Time** | equals, before, after, exists, is null                                                                     |
| **Enum**      | equals, not equals, in, not in, exists                                                                     |
| **Object**    | exists, not exists                                                                                         |
| **Array**     | contains, size equals, size greater than, exists                                                           |

<Tip>
  Fields not in the schema can also be used — select a custom key and a data type selector appears so you can set the appropriate operators.
</Tip>

#### Builder sections by operation type

<Tabs>
  <Tab title="Find / Find One">
    * **Filter**: Condition rows to define which documents to match
    * **Sort**: Add sort fields with ASC/DESC direction
    * **Projection**: Select fields to include or exclude from results
    * **Pagination** (find only): Set **Limit** (max documents) and **Skip** (offset) values
  </Tab>

  <Tab title="Insert / Insert Many">
    * **Document fields**: Auto-populated from the collection schema with appropriate input types per field
    * `_id` is auto-included with an "auto-generated" indicator
    * Array fields have an **+ Add item** button
    * Each field supports static values or `${paramName}` dynamic references
  </Tab>

  <Tab title="Update / Update Many">
    * **Filter section**: Same condition row builder as Find — defines which documents to update
    * **Update section**: Define what to change in matching documents:

    | Update operator | Description               |
    | --------------- | ------------------------- |
    | `$set`          | Replace field value       |
    | `$unset`        | Remove field              |
    | `$inc`          | Increment number          |
    | `$push`         | Add to array              |
    | `$pull`         | Remove from array         |
    | `$addToSet`     | Add unique value to array |
  </Tab>

  <Tab title="Delete / Delete Many">
    * **Filter section**: Same condition row builder as Find — defines which documents to delete

    <Warning>
      A warning banner is always displayed: "This operation will permanently delete matching documents."
    </Warning>
  </Tab>
</Tabs>

#### Testing operations

The existing 3-panel test modal is enhanced with the visual builder:

* **Left panel**: Input parameters — fill in test values for `${paramName}` references
* **Middle panel**: Shows the visual builder view of the query
* **Right panel**: Results displayed in tabular format with schema-derived column headers

For insert operations, a **Quick Find** button appears after a successful test, letting you immediately verify the inserted document.

***

## Working with FlowX Database in workflows

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/database_node_workflow.png)
</Frame>

FlowX Database integrates directly with the workflow designer through the "Data Source" node type:

<Steps>
  <Step title="Add Data Source node">
    In your workflow, add a new node and select the 'DATA\_SOURCE' type.
  </Step>

  <Step title="Configure data source">
    In the node properties panel:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/data_source_node_config.png)
    </Frame>

    1. Choose "FlowX Database" as the system type from the dropdown
    2. Select your collection from the available options
    3. Choose the operation you want to perform (find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany)
  </Step>

  <Step title="Configure operation parameters">
    Set the parameters for your selected operation. The available parameters will depend on the operation type:

    * **filter** - For find operations, define the criteria to match documents
    * **sort** - For find operations, specify the sorting order for results
    * **document** - For insert operations, define the document to insert
    * **update** - For update operations, define the document to update
    * **delete** - For delete operations, define the criteria to match documents
    * **skip** - For find operations, specify the number of documents to skip
    * **limit** - For find operations, specify the maximum number of documents to return
    * **projection** - For find operations, specify the fields to include or exclude in the results

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/config_operation_params.png)
    </Frame>

    You can use static JSON or reference process variables using the expression syntax.
  </Step>

  <Step title="Set response key">
    Specify where the operation result should be stored in the process instance. This makes the data available to subsequent nodes in your workflow.
  </Step>
</Steps>

<Accordion title="Example: Using filter parameter in find operation">
  ```json theme={"system"}
  {
    "age": { "$gt": 30 },
    "status": "active"
  }
  ```

  This filter will return all documents where the age is greater than 30 and the status is "active".

  <Info>
    For more information about MongoDB comparison operators like \$gt, see [Comparison Query Operators](https://www.mongodb.com/docs/manual/reference/operator/query/comparison/).
  </Info>
</Accordion>

<Accordion title="Example: Using process variables in parameters">
  ```json theme={"system"}
  {
    "customerId": "${processInstance.customerData.id}"
  }
  ```

  This filter uses a value from the process instance to find documents matching a specific customer ID.

  <Info>
    Learn more about MongoDB query syntax in the [Query Documents Tutorial](https://www.mongodb.com/docs/manual/tutorial/query-documents/).
  </Info>
</Accordion>

## MongoDB operations supported

FlowX Database uses MongoDB's query capabilities through the **nosql-db-runner** service, providing pure MongoDB functionality. For detailed information about MongoDB query operators, filters, and syntax, refer to the [MongoDB Query and Projection Operators documentation](https://www.mongodb.com/docs/manual/reference/operator/query/).

The following MongoDB operations are supported in FlowX Database. Each tab includes practical examples that you can use as a starting point for your own operations.

<Tabs>
  <Tab title="find">
    **Parameters:**

    For complete documentation on find operations and query syntax, see [MongoDB db.collection.find()](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/).

    * **filter** (document, optional): Criteria to match documents. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
    * **sort** (document, optional): Document specifying the sorting order. See [Sort Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/)
    * **skip** (integer, optional): Number of documents to skip. See [Limit Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.skip/)
    * **limit** (integer, optional): Maximum number of documents to return. See [Limit Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.limit/)
    * **projection** (document, optional): Fields to include or exclude. See [Project Fields](https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/)

    <Accordion title="Example: List active customers">
      This example finds all active customers, sorts them by registration date (newest first), limits to 10 results, and returns only specific fields.

      Operation name: listActiveCustomers

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "status": "active"
          }
          ```
        </Tab>

        <Tab title="sort">
          ```json theme={"system"}
          {
            "customerSince": -1
          }
          ```
        </Tab>

        <Tab title="projection">
          ```json theme={"system"}
          {
            "customerId": 1,
            "firstName": 1,
            "lastName": 1,
            "email": 1,
            "status": 1,
            "_id": 0
          }
          ```
        </Tab>

        <Tab title="skip">
          ```
          0
          ```
        </Tab>

        <Tab title="limit">
          ```
          10
          ```
        </Tab>
      </Tabs>

      This operation will return up to 10 active customers, with the most recently registered customers first.
    </Accordion>

    <Accordion title="Example: Find products by category and price">
      This example finds products in a specific category within a price range.

      Operation name: findAffordableElectronics

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "category": "electronics",
            "price": { "$gte": 10, "$lte": 100 }
          }
          ```
        </Tab>

        <Tab title="sort">
          ```json theme={"system"}
          {
            "price": 1
          }
          ```
        </Tab>

        <Tab title="projection">
          ```json theme={"system"}
          {
            "productName": 1,
            "price": 1,
            "rating": 1,
            "inStock": 1,
            "_id": 0
          }
          ```
        </Tab>

        <Tab title="limit">
          ```
          20
          ```
        </Tab>
      </Tabs>

      This operation will return up to 20 electronics products with prices between $10 and $100, sorted from lowest to highest price.
    </Accordion>
  </Tab>

  <Tab title="findOne">
    **Parameters:**

    For complete documentation on findOne operations, see [MongoDB db.collection.findOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.findOne/).

    * **filter** (document, optional): Criteria to match the document. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
    * **projection** (document, optional): Fields to include or exclude. See [Project Fields](https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/)
    * **sort** (document, optional): Document specifying the sorting order. See [Sort Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/)

    <Accordion title="Example: Find customer by ID">
      This example retrieves a single customer by their unique customer ID.

      Operation name: findCustomerById

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "customerId": "${processInstance.customerId}"
          }
          ```
        </Tab>

        <Tab title="projection">
          ```json theme={"system"}
          {
            "firstName": 1,
            "lastName": 1,
            "email": 1,
            "phone": 1,
            "status": 1,
            "customerSince": 1,
            "address": 1,
            "_id": 0
          }
          ```
        </Tab>
      </Tabs>

      This operation uses a process variable for the customer ID and returns specific customer fields. Since findOne only returns one document, sort is usually unnecessary unless you need the first document matching certain criteria.
    </Accordion>

    <Accordion title="Example: Find latest order">
      This example finds the most recent order for a customer.

      Operation name: findLatestOrder

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "customerId": "${processInstance.customerId}"
          }
          ```
        </Tab>

        <Tab title="sort">
          ```json theme={"system"}
          {
            "orderDate": -1
          }
          ```
        </Tab>

        <Tab title="projection">
          ```json theme={"system"}
          {
            "orderId": 1,
            "orderDate": 1,
            "totalAmount": 1,
            "status": 1,
            "items": 1,
            "_id": 0
          }
          ```
        </Tab>
      </Tabs>

      This operation will find the most recent order for a specific customer by sorting by orderDate in descending order and returning only the first match.
    </Accordion>
  </Tab>

  <Tab title="insertOne">
    **Parameters:**

    For complete documentation on insertOne operations, see [MongoDB db.collection.insertOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertOne/).

    * **document** (document, required): The document to insert. See [Insert Documents](https://www.mongodb.com/docs/manual/tutorial/insert-documents/)

    <Accordion title="Example: Create a new customer">
      This example inserts a new customer record using data from a process instance.

      Operation name: createCustomer

      <Tabs>
        <Tab title="document">
          ```json theme={"system"}
          {
            "customerId": "${processInstance.customerData.id}",
            "firstName": "${processInstance.customerData.firstName}",
            "lastName": "${processInstance.customerData.lastName}",
            "email": "${processInstance.customerData.email}",
            "phone": "${processInstance.customerData.phone}",
            "status": "active",
            "customerSince": "${processInstance.customerData.registrationDate}",
            "address": {
              "street": "${processInstance.customerData.address.street}",
              "city": "${processInstance.customerData.address.city}",
              "state": "${processInstance.customerData.address.state}",
              "zipCode": "${processInstance.customerData.address.zipCode}"
            }
          }
          ```
        </Tab>
      </Tabs>

      This operation creates a new customer document with nested address data, using values from the process instance.
    </Accordion>

    <Accordion title="Example: Log a system event">
      This example logs a system event with static and dynamic data.

      Operation name: logSystemEvent

      <Tabs>
        <Tab title="document">
          ```json theme={"system"}
          {
            "eventType": "user_action",
            "action": "${processInstance.actionType}",
            "timestamp": "${processInstance.currentDateTime}",
            "userId": "${processInstance.userId}",
            "details": "${processInstance.actionDetails}",
            "source": "workflow",
            "processId": "${processInstance.id}"
          }
          ```
        </Tab>
      </Tabs>

      This operation creates an event log entry with information about user actions in the system.
    </Accordion>
  </Tab>

  <Tab title="insertMany">
    **Parameters:**

    For complete documentation on insertMany operations, see [MongoDB db.collection.insertMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertMany/).

    * **documents** (array, required): Array of documents to insert. See [Insert Documents](https://www.mongodb.com/docs/manual/tutorial/insert-documents/)

    <Accordion title="Example: Import multiple customers">
      This example inserts multiple customer records at once, typically from an imported data source.

      Operation name: importCustomers

      <Tabs>
        <Tab title="documents">
          ```json theme={"system"}
          [
            {
              "customerId": "CUST001",
              "firstName": "John",
              "lastName": "Doe",
              "email": "john.doe@example.com",
              "status": "active",
              "customerSince": "2025-01-15"
            },
            {
              "customerId": "CUST002",
              "firstName": "Jane",
              "lastName": "Smith",
              "email": "jane.smith@example.com",
              "status": "active",
              "customerSince": "2025-01-20"
            },
            {
              "customerId": "CUST003",
              "firstName": "Robert",
              "lastName": "Johnson",
              "email": "robert.j@example.com",
              "status": "inactive",
              "customerSince": "2024-11-05"
            }
          ]
          ```
        </Tab>
      </Tabs>

      This operation inserts multiple customer records at once. In a real scenario, you would typically reference a process variable containing the array: `{processInstance.importedCustomers}`
    </Accordion>

    <Accordion title="Example: Create order items">
      This example creates multiple order items for a single order.

      Operation name: createOrderItems

      <Tabs>
        <Tab title="documents">
          ```json theme={"system"}
          [
            {
              "orderId": "${processInstance.orderId}",
              "productId": "${processInstance.items[0].productId}",
              "quantity": "${processInstance.items[0].quantity}",
              "unitPrice": "${processInstance.items[0].price}",
              "subtotal": "${processInstance.items[0].subtotal}"
            },
            {
              "orderId": "${processInstance.orderId}",
              "productId": "${processInstance.items[1].productId}",
              "quantity": "${processInstance.items[1].quantity}",
              "unitPrice": "${processInstance.items[1].price}",
              "subtotal": "${processInstance.items[1].subtotal}"
            }
          ]
          ```
        </Tab>
      </Tabs>

      This operation creates multiple order item records for a single order. In practice, you would use `{processInstance.items}` directly if your process data model matches the database structure.
    </Accordion>
  </Tab>

  <Tab title="updateOne">
    **Parameters:**

    For complete documentation on updateOne operations, see [MongoDB db.collection.updateOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateOne/).

    * **filter** (document, required): Criteria to match the document to update. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
    * **update** (document, required): Update operations to apply. See [Update Operators](https://www.mongodb.com/docs/manual/reference/mql/update/)

    <Warning>
      **Important Update Behavior**: When using update operations without the `$set` operator, the entire document will be replaced with the new data. This means any fields not included in your update payload will be removed from the document. Always use the `$set` operator to update specific fields while preserving others.
    </Warning>

    <Accordion title="Example: Update customer status">
      This example updates a customer's status and records when the change occurred.

      Operation name: updateCustomerStatus

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "customerId": "${processInstance.customerId}"
          }
          ```
        </Tab>

        <Tab title="update">
          ```json theme={"system"}
          {
            "$set": {
              "status": "${processInstance.newStatus}",
              "lastUpdated": "${processInstance.currentDate}",
              "statusReason": "${processInstance.statusChangeReason}"
            }
          }
          ```
        </Tab>
      </Tabs>

      This operation updates a customer's status along with the reason and timestamp.
    </Accordion>

    <Accordion title="Example: Update order with tracking information">
      This example updates an order with shipping details and increments a counter.

      Operation name: updateOrderShipping

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "orderId": "${processInstance.orderId}"
          }
          ```
        </Tab>

        <Tab title="update">
          ```json theme={"system"}
          {
            "$set": {
              "status": "shipped",
              "shippingDetails": {
                "carrier": "${processInstance.shippingData.carrier}",
                "trackingNumber": "${processInstance.shippingData.trackingNumber}",
                "estimatedDelivery": "${processInstance.shippingData.estimatedDelivery}"
              },
              "lastUpdated": "${processInstance.currentDateTime}"
            },
            "$inc": {
              "statusUpdates": 1
            }
          }
          ```
        </Tab>
      </Tabs>

      This operation updates an order with shipping information, sets the status to "shipped", and increments a counter tracking the number of status updates.
    </Accordion>
  </Tab>

  <Tab title="updateMany">
    **Parameters:**

    For complete documentation on updateMany operations, see [MongoDB db.collection.updateMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateMany/).

    * **filter** (document, required): Criteria to match documents to update. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
    * **update** (document, required): Update operations to apply. See [Update Operators](https://www.mongodb.com/docs/manual/reference/mql/update/)

    <Warning>
      **Important Update Behavior**: When using update operations without the `$set` operator, the entire document will be replaced with the new data. This means any fields not included in your update payload will be removed from the document.

      For example, if a document has `id`, `name`, and `email`, and you update only the `name` field without using `$set`, the `email` field will be deleted. Always use the `$set` operator to update specific fields while preserving others.
    </Warning>

    <Accordion title="Example: Deactivate inactive customers">
      This example updates the status of multiple customers based on their last activity date.

      Operation name: deactivateInactiveCustomers

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "lastActivityDate": { "$lt": "${processInstance.thresholdDate}" },
            "status": "active"
          }
          ```
        </Tab>

        <Tab title="update">
          ```json theme={"system"}
          {
            "$set": {
              "status": "inactive",
              "deactivationDate": "${processInstance.currentDate}",
              "deactivationReason": "inactivity"
            }
          }
          ```
        </Tab>
      </Tabs>

      This operation identifies all active customers whose last activity date is older than a threshold date and marks them as inactive.

      <Info>
        **Key MongoDB Operators**: This example uses `$lt` (less than) for date comparison and `$set` to update specific fields without affecting other customer data. The `$set` operator is essential for partial document updates.
      </Info>
    </Accordion>

    <Accordion title="Example: Update multiple customers by ID list">
      This example demonstrates updating multiple specific customers using the `$in` operator.

      Operation name: updateCustomersByIdList

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "customerId": { "$in": ["${processInstance.customerIds}"] }
          }
          ```
        </Tab>

        <Tab title="update">
          ```json theme={"system"}
          {
            "$set": {
              "lastContactedDate": "${processInstance.currentDate}",
              "contactMethod": "${processInstance.contactMethod}",
              "notes": "${processInstance.contactNotes}"
            }
          }
          ```
        </Tab>
      </Tabs>

      This operation updates all customers whose IDs are in the provided list, setting contact information for multiple customers at once.

      <Tip>
        **Standard MongoDB Pattern**: The combination of `$in` for filtering and `$set` for updating is a standard pattern in MongoDB. Use `$in` when you need to match against a list of values, and always use `$set` to avoid replacing the entire document.
      </Tip>
    </Accordion>

    <Accordion title="Example: Apply discount to products">
      This example applies a discount to all products in a specific category.

      Operation name: applySeasonalDiscount

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "category": "${processInstance.discountCategory}",
            "onSale": false
          }
          ```
        </Tab>

        <Tab title="update">
          ```json theme={"system"}
          {
            "$mul": {
              "price": ${processInstance.discountFactor}
            },
            "$set": {
              "onSale": true,
              "discountPercent": "${processInstance.discountPercent}",
              "saleEndDate": "${processInstance.saleEndDate}"
            }
          }
          ```
        </Tab>
      </Tabs>

      This operation applies a discount to all products in a specific category by multiplying the price by a discount factor (e.g., 0.8 for 20% off) and setting sale-related fields.

      <Tip>
        **MongoDB Operators in Action**: This example demonstrates essential MongoDB operators:

        * `$mul` multiplies the price by the discount factor
        * `$set` updates specific fields without affecting others
        * In the filter, you could use `$in` to target multiple categories: `"category": {"$in": ["electronics", "clothing"]}`
      </Tip>
    </Accordion>
  </Tab>

  <Tab title="deleteOne">
    **Parameters:**

    For complete documentation on deleteOne operations, see [MongoDB db.collection.deleteOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteOne/).

    * **filter** (document, required): Criteria to match the document to delete. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)

    <Accordion title="Example: Delete a customer record">
      This example removes a single customer record by ID.

      Operation name: deleteCustomer

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "customerId": "${processInstance.customerIdToDelete}"
          }
          ```
        </Tab>
      </Tabs>

      This operation deletes a customer record with the specified ID. Make sure to implement proper validation and confirmation before executing deletion operations.
    </Accordion>

    <Accordion title="Example: Remove abandoned cart">
      This example removes an abandoned shopping cart after confirmation.

      Operation name: removeAbandonedCart

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "cartId": "${processInstance.cartId}",
            "status": "abandoned",
            "lastUpdated": { "$lt": "${processInstance.thresholdDate}" }
          }
          ```
        </Tab>
      </Tabs>

      This operation deletes a shopping cart that's been marked as abandoned and hasn't been updated since a specific date.
    </Accordion>
  </Tab>

  <Tab title="deleteMany">
    **Parameters:**

    For complete documentation on deleteMany operations, see [MongoDB db.collection.deleteMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteMany/).

    * **filter** (document, required): Criteria to match documents to delete. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)

    <Accordion title="Example: Purge temporary records">
      This example removes all temporary records older than a specified date.

      Operation name: purgeTemporaryRecords

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "status": "temporary",
            "createdDate": { "$lt": "${processInstance.purgeThresholdDate}" }
          }
          ```
        </Tab>
      </Tabs>

      This operation removes all documents marked as "temporary" that were created before a specific date. Use with caution as this will delete all matching records.
    </Accordion>

    <Accordion title="Example: Clear completed tasks">
      This example removes all completed tasks for a specific user.

      Operation name: clearCompletedTasks

      <Tabs>
        <Tab title="filter">
          ```json theme={"system"}
          {
            "assignedTo": "${processInstance.userId}",
            "status": "completed",
            "completedDate": { "$lt": "${processInstance.olderThanDate}" }
          }
          ```
        </Tab>
      </Tabs>

      This operation removes all tasks that are marked as completed, were assigned to a specific user, and were completed before a certain date.
    </Accordion>
  </Tab>
</Tabs>

<Warning>
  Always use caution with update and delete operations, especially those that affect multiple documents (updateMany, deleteMany). Always include specific filter criteria to avoid unintended changes to your data.
</Warning>

## Real-world example: Customer management system

This example demonstrates how a customer management system could use FlowX Database to persist and share customer data across different processes.

<Accordion title="Setup">
  <Steps>
    <Step title="Create Customer collection">
      Create a new FlowX Database data source named "Customers".

      <Frame>
        ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/create_cs_db.png)
      </Frame>
    </Step>

    <Step title="Define operations">
      Create the following operations:

      <Tabs>
        <Tab title="findCustomer">
          **Operation Type**: findOne

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/findCustomer.png)
          </Frame>

          **Parameters**:

          ```json theme={"system"}
          {
            "filter": {
              "customerId": "${processInstance.customerId}"
            },
            "projection": {
              "firstName": 1,
              "lastName": 1,
              "email": 1,
              "phone": 1,
              "status": 1,
              "customerSince": 1,
              "_id": 0
            }
          }
          ```

          This operation retrieves a single customer by their customerId, returning only selected fields.
        </Tab>

        <Tab title="createCustomer">
          **Operation Type**: insertOne

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/createCustomer.png)
          </Frame>

          **Parameters**:

          ```json theme={"system"}
          {
            "document": {
              "customerId": "${processInstance.customerData.id}",
              "firstName": "${processInstance.customerData.firstName}",
              "lastName": "${processInstance.customerData.lastName}",
              "email": "${processInstance.customerData.email}",
              "phone": "${processInstance.customerData.phone}",
              "status": "active",
              "customerSince": "${processInstance.customerData.registrationDate}",
              "address": {
                "street": "${processInstance.customerData.address.street}",
                "city": "${processInstance.customerData.address.city}",
                "state": "${processInstance.customerData.address.state}",
                "zipCode": "${processInstance.customerData.address.zipCode}"
              }
            }
          }
          ```

          This operation inserts a new customer document using data from the process instance.
        </Tab>

        <Tab title="updateCustomerStatus">
          **Operation Type**: updateOne

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/updateCustomerStatus.png)
          </Frame>

          **Parameters**:

          ```json theme={"system"}
          {
            "filter": {
              "customerId": "${processInstance.customerId}"
            },
            "update": {
              "$set": {
                "status": "${processInstance.newStatus}",
                "lastUpdated": "${processInstance.currentDate}"
              }
            }
          }
          ```

          This operation updates a customer's status and sets the lastUpdated timestamp.
        </Tab>

        <Tab title="listActiveCustomers">
          **Operation Type**: find()

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/listActiveCustomers.png)
          </Frame>

          **Parameters**:

          ```json theme={"system"}
          {
            "filter": {
              "status": "active"
            },
            "sort": {
              "customerSince": -1
            },
            "limit": 50,
            "projection": {
              "customerId": 1,
              "firstName": 1,
              "lastName": 1,
              "email": 1,
              "status": 1,
              "_id": 0
            }
          }
          ```

          This operation retrieves a list of active customers, sorted by registration date (newest first), limited to 50 results.
        </Tab>
      </Tabs>
    </Step>
  </Steps>
</Accordion>

<Accordion title="Customer support process">
  In this process:

  1. Support agent enters the customer ID
  2. A Data Source node retrieves the customer details from the Customers collection
  3. Customer information is displayed to the agent
  4. After resolving the issue, the support agent updates the customer status
  5. Another Data Source node updates the customer record in the database
</Accordion>

<Accordion title="Benefits demonstrated">
  <Card>
    This example shows how FlowX Database:

    * Enables data persistence across multiple processes
    * Provides a single source of truth for customer data
    * Simplifies data retrieval and updates
    * Eliminates the need for external systems to store basic customer information
  </Card>
</Accordion>

## Limitations and considerations

<Expandable title="Current limitations of FlowX Database">
  <Warning>
    Multiple versions of documents are stored in the collection. Upon retrieval, all data that fits the filter conditions will be retrieved regardless of version.
  </Warning>

  <Warning>
    No automatic migration capabilities are available. Any migration will need to be done manually by the DevOps team.
  </Warning>

  <Warning>
    In the initial release, FlowX Database does not support transactions across multiple collections.
  </Warning>

  <Warning>
    Data validation based on a schema is not yet supported.
  </Warning>
</Expandable>

## Best practices

<Check>
  **Design before implementation**: Plan your collections and operations carefully before implementation.
</Check>

<Check>
  **Keep document structure simple**: Avoid deeply nested structures for better performance and easier querying.
</Check>

<Check>
  **Use meaningful names**: Choose clear names for collections and operations.
</Check>

<Check>
  **Limit document size**: Keep individual documents under 16MB for optimal performance.
</Check>

<Check>
  **Test operations thoroughly**: Use the testing functionality to ensure operations work as expected.
</Check>

<Check>
  **Consider indexing**: For large collections, consider indexing frequently queried fields.
</Check>

<Check>
  **Provide default values**: Ensure all data types have default values (e.g., empty string for null, 0 for integers).
</Check>

## Troubleshooting

<Accordion title="Operation fails with filter error">
  <Steps>
    <Step title="Problem">
      Find operation fails with an error related to the filter syntax.
    </Step>

    <Step title="Solution">
      Check your filter syntax to ensure it follows MongoDB query syntax. Common issues:

      * Missing quotes around string values
      * Incorrect operator syntax (e.g., using > instead of \$gt)
      * Mismatched brackets or braces
    </Step>
  </Steps>
</Accordion>

<Accordion title="Documents not appearing in results">
  <Steps>
    <Step title="Problem">
      Your query doesn't return expected documents.
    </Step>

    <Step title="Solution">
      * Verify your filter conditions are correct
      * Check if documents actually exist in the collection
      * Try a more general query to see if documents are returned
      * Check if field names in your filter match exactly with the document structure
    </Step>
  </Steps>
</Accordion>

<Accordion title="Performance issues with large result sets">
  <Steps>
    <Step title="Problem">
      Queries returning large amounts of data are slow.
    </Step>

    <Step title="Solution">
      * Add pagination using skip and limit parameters
      * Add more specific filter conditions
      * Use projection to return only needed fields
      * Consider indexing frequently queried fields
    </Step>
  </Steps>
</Accordion>

<Accordion title="Insert operation fails">
  <Steps>
    <Step title="Problem">
      Insert operation fails with an error.
    </Step>

    <Step title="Solution">
      * Check that your document JSON is valid
      * Ensure document size is under 16MB
      * Verify all required fields are present
      * Check for any unique constraint violations
    </Step>
  </Steps>
</Accordion>

## Related features

<CardGroup>
  <Card title="Data Search" icon="magnifying-glass" href="../core-extensions/search-data-service">
    Learn about the Data Search service for indexing and searching process data.
  </Card>

  <Card title="Integration Management" icon="plug" href="./integration-designer">
    Understand how to manage integrations with external systems.
  </Card>

  <Card title="Workflow" icon="diagram-project" href="../integrations/integration-designer#workflows">
    See how workflows can interact with data sources.
  </Card>

  <Card title="Process Data Model" icon="sitemap" href="../../building-blocks/process/data-model">
    Learn about data models used within processes.
  </Card>
</CardGroup>

## Summary

FlowX Database provides a persistence layer that enables you to store and share data across different processes and projects. By using MongoDB's capabilities through the **nosql-db-runner** service, FlowX Database offers:

1. **Flexible data storage** for any structured data
2. **Data sharing** between process instances
3. **Integration** with workflows
4. **Independence** from external systems for basic data persistence

## MongoDB learning resources

To get the most out of FlowX Database, familiarize yourself with MongoDB concepts and operations:

<CardGroup>
  <Card title="MongoDB Manual" icon="book" href="https://www.mongodb.com/docs/manual/">
    Complete MongoDB documentation covering all operations and concepts
  </Card>

  <Card title="Query Tutorial" icon="magnifying-glass" href="https://www.mongodb.com/docs/manual/tutorial/query-documents/">
    Learn how to construct effective MongoDB queries
  </Card>

  <Card title="Update Operations" icon="pen-to-square" href="https://www.mongodb.com/docs/manual/tutorial/update-documents/">
    Master document update operations and operators
  </Card>

  <Card title="Data Modeling" icon="sitemap" href="https://www.mongodb.com/docs/manual/core/data-modeling-introduction/">
    Best practices for structuring your data in MongoDB
  </Card>
</CardGroup>

## FAQs

<Accordion title="When should I use Data Search vs. FlowX Database?">
  FlowX Database does not replace Data Search. Each serves different purposes in the platform.

  <Tabs>
    <Tab title="FlowX Database">
      * Acts as a persistent data store
      * Optimized for CRUD operations
      * Stores structured business data
      * Designed for sharing data across processes
      * Uses MongoDB as the underlying technology (via nosql-db-runner service)
    </Tab>

    <Tab title="Data Search">
      * Provides indexing and search capabilities
      * Optimized for quick lookups and aggregations
      * Used for debugging and analytics
      * Enables searching across process instances
      * Uses Elasticsearch as the underlying technology
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="What types of data should I store in FlowX Database?">
  FlowX Database is designed for **operational data with temporary character**, including:

  * **Dashboard data**: Aggregated information for reporting and visualization. For example, create operations that gather information from multiple processes and pull all the data to calculate sums, averages, or other metrics for executive dashboards
  * **Cached data**: Frequently accessed information that changes periodically, such as:
    * Daily exchange rates for financial calculations
    * Product catalogs that update weekly
    * Configuration data that multiple processes need to access
  * **Internal operational comments**: Information that needs to be shared between users but shouldn't reach business systems, such as:
    * Internal comments in a client's profile for bank tellers
    * Notes and annotations that support decision-making across different process instances
    * Communication logs between team members working on the same case
  * **Shared process data**: Information that needs to be accessed across multiple process instances - this solves the key pain point of data sharing between different process instances
  * **Temporary operational data**: Working data that supports business processes but isn't part of your permanent records

  <Warning>
    **Important**: FlowX Database should **not become your primary book of records** or system of record. Use it for operational data that supports your processes, not for critical business data that requires long-term retention and governance.
  </Warning>
</Accordion>

<Accordion title="Can I share FlowX Database collections between different projects?">
  Yes, you can share collections between projects using the library approach:

  1. **Create collections in one project**: Set up your FlowX Database collections in a primary project
  2. **Include as libraries**: Add these collections as libraries in other projects that need access
  3. **Maintain consistency**: This approach ensures all projects use the same data structures and operations
  4. **Future-proof management**: Having centralized collection definitions makes updates and maintenance easier across all projects

  This pattern is particularly useful for shared reference data, common configurations, or cross-project operational data.

  <Info>
    **Collection Ownership**: Each FlowX Database collection has an owner - either the project where it was created or the library that contains it. By default, only processes and workflows within the same project can access a collection. If you need to access the same collection from multiple projects, create it in a library and then include that library in all projects that need access.
  </Info>
</Accordion>

<Accordion title="Why doesn't FlowX Database support automatic data migration?">
  FlowX Database intentionally does not provide automatic migration capabilities for several important reasons:

  * **Data integrity**: Many documents need to remain in their original format to maintain historical accuracy and compliance requirements
  * **Process dependencies**: Existing processes may depend on specific data structures, and automatic changes could break functionality
  * **Business context**: Data migration often requires business logic and context that automated systems cannot provide
  * **Risk management**: Manual migration allows for proper testing and validation before changes are applied

  When you need to modify data structures, plan for manual migration processes with proper testing and validation procedures handled by your DevOps team.
</Accordion>

<Accordion title="Can I store different types of documents in the same collection?">
  **No, this is strongly discouraged.** Each collection should contain documents with the same structure and purpose.

  **DON'T DO IT** - Mixing different document types in one collection can lead to:

  * **Query complexity**: Filtering becomes more complex when documents have different schemas
  * **Performance issues**: Indexes become less effective with mixed document types
  * **Maintenance problems**: Updates and changes become harder to manage
  * **Data consistency**: Harder to ensure data quality and validation

  Instead, create separate collections for each document type, even if they seem related. This follows MongoDB best practices and keeps your data organized and manageable.
</Accordion>

<Accordion title="How does FlowX Database solve cross-process data sharing?">
  FlowX Database solves the key pain point of **accessing the same data from multiple process instances**:

  * **Cross-instance access**: Multiple process instances can read from and write to the same collections simultaneously
  * **Data persistence**: Data remains available even after individual processes complete
  * **Concurrent access**: The underlying MongoDB technology (via nosql-db-runner) handles concurrent read/write operations safely
  * **Shared state**: Enables complex workflows where processes need to coordinate through shared data

  This capability enables use cases like multi-step approval processes, shared customer data across different business processes, and coordinated workflows that span multiple process instances - addressing a major limitation of traditional process-scoped data storage.
</Accordion>

<Accordion title="What's the relationship between FlowX Database and the nosql-db-runner service?">
  FlowX Database is powered by the **nosql-db-runner** microservice, which provides:

  * **Pure MongoDB functionality**: Direct access to MongoDB operations within the FlowX ecosystem
  * **Native integration**: Connection between FlowX workflows and MongoDB operations
  * **Scalable architecture**: A dedicated service that can be scaled independently based on database operation needs

  The nosql-db-runner acts as the bridge between FlowX's workflow engine and MongoDB, enabling you to use MongoDB's full capabilities while maintaining FlowX's process orchestration capabilities.
</Accordion>

***

## Academy courses

<CardGroup>
  <Card title="Integration Designer course" icon="graduation-cap" href="https://academy.flowx.ai/explore/integration-designer">
    Hands-on course covering systems, data sources, workflows, and database integration patterns
  </Card>

  <Card title="Data Mappers course" icon="graduation-cap" href="https://academy.flowx.ai/explore/5data-mappers">
    Learn data mapping and transformation between process and integration workflows
  </Card>
</CardGroup>

<Tip>
  **Academy playground** — explore the [**database**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/f69d3816-8746-43bc-ac89-121a28710ee5/config/4082e8f4-2f17-4071-84ea-a0692b34fc83/processes) project for working examples of find, findOne, insert, and update operations.
</Tip>


# Incoming Webhooks
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/incoming-webhooks

Trigger FlowX processes when an external system sends an HTTP POST. Secure with API keys, event-driven, no polling.

## What is an incoming webhook?

A webhook is an HTTP endpoint that an external system calls to notify FlowX when an event happens. Instead of FlowX polling for updates, the third-party system sends an HTTP POST the moment something occurs — and FlowX starts a process in response. Common uses include receiving events from payment processors, CRMs, ERPs, or CI/CD pipelines.

## Overview

Incoming Webhooks allow external systems to trigger FlowX processes by sending HTTP POST requests to a generated URL. Each webhook gets a unique, cryptographically secure API key for authentication — no IMAP setup, no polling, just a direct HTTP call.

Use webhooks when you need to:

* **Receive events from third-party platforms** (payment processors, CRMs, ERPs) that support outbound webhooks
* **Trigger processes from CI/CD pipelines** or internal tools via simple HTTP calls
* **Replace polling-based integrations** with event-driven process starts

<CardGroup>
  <Card title="API key authentication" icon="key">
    Each webhook gets a unique, secure API key included in the URL
  </Card>

  <Card title="JSON payload forwarding" icon="code">
    Webhook body and HTTP headers are forwarded to the process instance as variables
  </Card>

  <Card title="Manage Triggers UI" icon="toggle-on">
    Activate, deactivate, and manage webhook URLs from Runtime Settings
  </Card>

  <Card title="Zero configuration" icon="bolt">
    No server settings needed — create the data source, connect to a process, activate
  </Card>
</CardGroup>

***

## How it works

<Steps>
  <Step title="Create an Incoming Webhook data source">
    In Integration Designer, create a new data source and select **Incoming Webhook**. Provide a name and optional description. No connection settings are required.
  </Step>

  <Step title="Connect to a Message Start Event">
    In your process definition, add a **Message Start Event** node. Set the **Trigger Type** to **Incoming Webhook** and select your webhook data source.
  </Step>

  <Step title="Commit and activate">
    Commit the version, then go to **Runtime** → **Manage Triggers**. The webhook appears as **Deactivated**. Click the action menu and select **Activate**.
  </Step>

  <Step title="Get the webhook URL">
    From the trigger's action menu, select **Get URL**. Copy the generated URL (includes the API key as a query parameter) and configure it in your external system.
  </Step>

  <Step title="External system sends POST request">
    When the external system POSTs JSON to the webhook URL, the `webhook-gateway` service validates the API key, publishes the event to Kafka, and the process engine starts a new process instance.
  </Step>
</Steps>

***

## Creating a webhook data source

<Steps>
  <Step title="Navigate to Data Sources">
    Go to **Integrations** → **Data Sources** in your project.
  </Step>

  <Step title="Add a new data source">
    Click **+** and select **Incoming Webhook** as the data source type.
  </Step>

  <Step title="Configure basic information">
    | Field           | Required | Description                                                                      |
    | --------------- | -------- | -------------------------------------------------------------------------------- |
    | **Name**        | Yes      | A unique name for the webhook (3–50 characters, letters, numbers, `[] () . _ -`) |
    | **Description** | No       | Purpose or context for this webhook                                              |
  </Step>

  <Step title="Create">
    Click **Create**. The webhook data source is ready to be connected to a process.
  </Step>
</Steps>

<Frame>
  ![Incoming Webhook data source page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_data_source_created.png)
</Frame>

<Info>
  Incoming Webhooks accept POST requests with JSON payloads (max 1 MB). No connection settings, credentials, or polling configuration is needed.
</Info>

<Warning>
  When deleting a webhook data source, deactivate it first and remove the URL from any third-party systems that use it. Deleting the webhook in FlowX does not notify external systems — they will continue sending requests that return errors.
</Warning>

***

## Connecting to a Message Catch Event

A webhook can drive two kinds of message catch events:

| Event placement                      | Trigger type set on the webhook | What the webhook does                           |
| ------------------------------------ | ------------------------------- | ----------------------------------------------- |
| **Message Start Event**              | `START_PROCESS`                 | Creates a new process instance on each POST     |
| **Message Catch Intermediate Event** | `RESUME_PROCESS`                | Resumes a process instance waiting on the catch |

The trigger type is set automatically based on which kind of event the webhook is attached to — there is no separate toggle to configure.

### On a Message Start Event

<Steps>
  <Step title="Open your process definition">
    Open the process in the Process Designer.
  </Step>

  <Step title="Add a Message Start Event node">
    Drag a **Message Start Event** from the Start Events section of the node palette onto the canvas.
  </Step>

  <Step title="Configure the Process Trigger">
    In the node configuration panel, under **Process Trigger**:

    * Set **Trigger Type** to **Incoming Webhook**
    * In **Select Webhook**, choose your webhook data source from the dropdown
  </Step>

  <Step title="Save the node">
    Click **Save** to persist the configuration.
  </Step>
</Steps>

<Frame>
  ![Message Start Event configured with Incoming Webhook trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_configured.png)
</Frame>

### On a Message Catch Intermediate Event

Use a webhook on an intermediate catch event to resume a process instance that is waiting for an external signal — for example, a callback from a third-party document scanner, a downstream system confirming an enqueued job, or a manual operator action delivered over HTTP.

<Steps>
  <Step title="Add a Webhook Trigger intermediate catch event">
    From the node palette, drag a **Webhook Trigger** message catch event onto the canvas at the point where the process should pause.
  </Step>

  <Step title="Select the webhook data source">
    In the node configuration panel, set the **Data Source** dropdown to the webhook that drives this catch event. The **Webhook Correlation Key** field appears as read-only and shows the correlation key defined on the webhook itself — included here so you can see how incoming requests are matched.
  </Step>

  <Step title="Set the Process Correlation Key">
    Set **Process Correlation Key** to a business or process variable from the data model (for example, `applicationId`, `orderId`). At runtime this value is matched against the incoming payload to identify which waiting process instance to resume.
  </Step>

  <Step title="Set the Process Key">
    Set **Process Key** to the data-model path where the incoming webhook payload should be stored when the catch fires.
  </Step>

  <Step title="Save the node">
    Click **Save** to persist the configuration.
  </Step>
</Steps>

<Info>
  The same webhook data source can drive multiple intermediate catch events as long as the Process Correlation Key disambiguates which instance to resume. Without a valid correlation match, the inbound request is rejected.
</Info>

#### Webhook Correlation Key path syntax

The **Webhook Correlation Key** points into the incoming webhook payload. It uses dotted-path notation and supports array indices in square brackets, so deeply nested provider payloads can be addressed directly.

| Path pattern                                      | Resolves to                                                            |
| ------------------------------------------------- | ---------------------------------------------------------------------- |
| `application.applicationId`                       | `payload.application.applicationId`                                    |
| `entry[0].changes[0].value.messages[0].text.body` | The first inbound text-message body in a Meta WhatsApp webhook payload |
| `data.orders[2].id`                               | The `id` of the third element of the `orders` array                    |

<Info>
  Array index syntax (`field[N]`) is supported in correlation keys, so the canonical Meta WhatsApp resume path works as-is. Paths like `entry[0]...` resolve directly and no longer need to be flattened in the producer before posting.
</Info>

If the path does not resolve in an incoming request (missing field, index out of bounds, null leaf), the request is rejected and the waiting process instance is not resumed.

***

## Managing webhooks at runtime

### Activating a webhook

For a webhook to appear in Manage Triggers:

1. The webhook data source must be created
2. The webhook must be connected to a Message Start Event node
3. The version must be committed

Navigate to **Runtime** → **Manage Triggers** to view and control webhooks:

| Column           | Description                    |
| ---------------- | ------------------------------ |
| **State**        | `Active` or `Deactivated`      |
| **Trigger Type** | `Webhook`                      |
| **Event Name**   | The webhook data source name   |
| **Location**     | Project and branch information |

Use the action menu (three-dot icon) to:

* **Activate** — Start accepting webhook requests
* **Deactivate** — Stop accepting requests. The API key and URL are preserved, so you can reactivate later without reconfiguring external systems.
* **Get URL** — View and copy the webhook URL with API key

<Tip>
  A single webhook can trigger multiple processes — add the same webhook data source to Message Start Event nodes in different process definitions. Each incoming request starts all connected processes.
</Tip>

<Frame>
  ![Manage Triggers showing active webhook](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
</Frame>

***

### Webhook URL and API key

When you activate a webhook and select **Get URL**, a modal displays:

* **Webhook URL** — The full URL including the API key as a `flowxApiKey` query parameter
* **Copy button** — Copies the URL to clipboard
* **Reset API Key** — Generates a new API key (invalidates the previous URL)

<Frame>
  ![Webhook URL modal with API key and Reset button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_url_modal.png)
</Frame>

**URL format:**

```
https://{services-host}/webhooks/incoming/{orgId}/{workspaceId}/{appId}/{resourceDefinitionId}?flowxApiKey={apiKey}
```

<Warning>
  Resetting the API key creates a new webhook URL. Update the URL in all third-party systems that use it, or they will receive `401 Unauthorized` errors.
</Warning>

***

## Provider adapters

When a webhook is created in the Integration Designer, the **Settings** tab now exposes:

* **Provider** — `GENERIC`, `SLACK`, or `META`. Once saved, the provider becomes immutable; create a new webhook to switch.
* **Provider secret** — the signing secret(s) obtained from the provider (for example, the Slack app's signing secret, or the Meta verify token + app secret pair). Stored encrypted; can be rotated independently of the API key.

For SaaS-hosted secrets you can also reference a config parameter using the `${configParam.name}` placeholder syntax — placeholders are resolved at registration time the same way LLM provider secrets are.

### Generic provider

The default. No signature validation is performed; authentication relies on the FlowX `flowxApiKey` and HTTPS. Use `GENERIC` for systems that do not sign their webhooks, or where signature validation is handled inside the process via a business-rule action on the raw headers.

### Slack provider

Performs Slack's standard signature check on every incoming request:

| Header                      | Purpose                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `X-Slack-Signature`         | HMAC-SHA256 signature of the version, timestamp, and raw body, prefixed with `v0=`. |
| `X-Slack-Request-Timestamp` | Unix timestamp; rejected if more than **5 minutes** out of skew.                    |

Requests that fail signature verification, that miss either header, or that arrive without a configured signing secret are rejected with `401 Unauthorized`.

Slack's URL-verification handshake is handled automatically — a `url_verification` POST with a `challenge` field receives the `challenge` value back as JSON, before the request is forwarded to the process. No process configuration is required for the handshake.

### Meta provider

Covers WhatsApp, Messenger, Instagram, and Threads. Meta-platform integrations share a common subscription model and signature scheme; the `META` adapter handles both.

Meta webhooks require **two** secrets, configured as masked inputs in the **Settings** panel:

| Field            | Purpose                                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Verify token** | Used during the GET URL-verification handshake. Choose any string and configure the same value on the Meta App developer console. |
| **App secret**   | The Meta App secret. Used to verify the `X-Hub-Signature-256` HMAC on every POST.                                                 |

Both values are stored together as a JSON-packed pair in the existing webhook secret field, encrypted at rest. Both are required; saving without either returns `WEBHOOK_META_SECRETS_REQUIRED 400`.

**GET URL verification.** Meta sends a GET request with `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge` query parameters when you save the webhook in the Meta App configuration. The gateway:

1. Confirms `hub.mode=subscribe`.
2. Confirms `hub.challenge` is present.
3. Compares the received `hub.verify_token` to the configured **Verify token** using a constant-time check.
4. Echoes the `hub.challenge` value back as plain text on success.

A mismatch or missing parameter returns `403 Forbidden` — Meta does not finalise the subscription.

**POST signature verification.** Every POST is signed by Meta with an `X-Hub-Signature-256` header (`sha256=<hex>`). The gateway recomputes the HMAC-SHA256 of the raw body with the configured **App secret** and rejects mismatches with `401 Unauthorized`.

### Path / provider mismatch

If a request hits the URL for one provider but the webhook registration is configured with a different provider, the gateway returns `400 Bad Request`. Always use the URL shown in the **Get URL** modal — it carries the correct provider segment for the registration.

***

## Webhook payload

When an external system POSTs to the webhook URL, the following data is available in the process instance:

```json theme={"system"}
{
  "webhookMessage": {
    "dateTime": "2026-03-23T15:30:00Z",
    "payload": {
      "orderId": "ORD-12345",
      "status": "completed",
      "amount": 299.99
    },
    "headers": {
      "Content-Type": ["application/json"],
      "X-Custom-Header": ["value"]
    }
  }
}
```

| Field      | Type              | Description                                                                                                                                                                    |
| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dateTime` | string (ISO 8601) | Ingestion time at FlowX — when `webhook-gateway` received the request. If the provider includes its own event timestamp in the payload, use that for the original event time.  |
| `payload`  | object or string  | The POST request body (parsed as JSON if valid, raw string otherwise)                                                                                                          |
| `headers`  | object            | All HTTP headers from the incoming request. Each header maps to an array of values — access the first value with `webhookMessage.headers.Content-Type[0]` in process variables |

<Frame>
  ![webhookMessage paramValue on a process instance](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhookExample.png)
</Frame>

<Note>
  `headers` includes values added by the FlowX ingress in addition to what the caller sent — typically `X-Forwarded-For`, `X-Real-IP`, `X-Request-ID`, `X-Forwarded-Host`, `X-Forwarded-Proto`. These are useful for logging and tracing but should not be confused with provider-supplied headers.
</Note>

<Info>
  The maximum payload size is **1 MB**. Requests exceeding this limit are rejected.
</Info>

***

## Authentication

Webhook authentication uses API keys:

* Each webhook registration gets a unique **32-byte, base64-URL-encoded** API key
* The key is passed as the `flowxApiKey` query parameter in the webhook URL
* Validation uses **constant-time comparison** to prevent timing attacks
* Invalid or missing keys return `401 Unauthorized`
* Inactive webhooks return `404 Not Found`

<Warning>
  FlowX validates provider signatures only for [providers with a built-in adapter](#provider-adapters). For the `GENERIC` provider — and for any third-party signature scheme without a dedicated adapter (`Stripe-Signature`, GitHub's `X-Hub-Signature-256` outside the Meta family, etc.) — signature headers are forwarded to the process in `webhookMessage.headers` but no validation is performed. Authentication for `GENERIC` registrations relies on the FlowX API key and HTTPS. The raw request body is not preserved after JSON parsing, which makes in-process HMAC verification impractical — for unsupported providers, design integrations assuming API key + HTTPS is the only authentication layer, or request a built-in adapter.
</Warning>

***

## Error handling

| HTTP Status                 | Cause                                         | Resolution                                                       |
| --------------------------- | --------------------------------------------- | ---------------------------------------------------------------- |
| `200 OK`                    | Webhook accepted and published to Kafka       | —                                                                |
| `400 Bad Request`           | Malformed payload (not valid JSON)            | Verify the POST body is valid JSON                               |
| `401 Unauthorized`          | Invalid or missing API key                    | Check the `flowxApiKey` parameter matches the active webhook URL |
| `404 Not Found`             | Webhook registration not found or deactivated | Verify the webhook is activated in Manage Triggers               |
| `413 Payload Too Large`     | Request body exceeds 1 MB                     | Reduce the payload size or split into multiple requests          |
| `500 Internal Server Error` | Processing error                              | Check webhook-gateway service logs                               |

Failed webhook events appear in **Runtime** → **Failed Triggers** with details about the failure cause.

***

## Best practices

<CardGroup>
  <Card title="Use HTTPS" icon="lock">
    Always use HTTPS URLs in production to protect the API key in transit
  </Card>

  <Card title="Validate payloads in your process" icon="shield-check">
    Add validation logic in your process to handle unexpected or malformed payloads gracefully
  </Card>

  <Card title="Monitor Failed Triggers" icon="triangle-exclamation">
    Regularly check the Failed Triggers section for webhook processing errors
  </Card>

  <Card title="Rotate keys periodically" icon="rotate">
    Use the Reset API Key feature to rotate webhook credentials, then update the URL in external systems
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Message Start Event" icon="play" href="../../building-blocks/node/message-events/message-catch-start-event">
    Configure message-based and webhook process triggers
  </Card>

  <Card title="Email Trigger" icon="envelope" href="./email-trigger">
    Start processes from incoming emails via IMAP
  </Card>

  <Card title="Integration Designer" icon="puzzle-piece" href="./integration-designer">
    Build integration workflows and manage data sources
  </Card>

  <Card title="Webhook Gateway setup" icon="gear" href="/5.9/setup-guides/webhook-gateway-setup">
    Deploy and configure the webhook-gateway microservice
  </Card>
</CardGroup>


# Integration Designer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/integration-designer

Connect FlowX to external systems via REST APIs using a drag-and-drop interface for data models, workflows, and endpoints.

<Card title="Did you know?" icon="info">
  Unlike [Postman](https://www.postman.com/), which focuses on API testing, the Integration Designer automates workflows between systems. With drag-and-drop ease, it handles REST API connections, real-time processes, and error management, making integrations scalable and maintainable.
</Card>

## Overview

Integration Designer facilitates the integration of the FlowX platform with external systems, applications, and data sources.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)
</Frame>

<Info>
  Integration Designer supports multiple data source types including RESTful Systems, FlowX Database, MCP Integration, Knowledge Base, Email Trigger, Email Sender, and Microsoft Outlook.
</Info>

<Info>
  Integration resources (data sources, workflows, systems) are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific integration resource, right-click it and select **View History**.
</Info>

***

## Key features

<Steps>
  <Step title="Drag-and-Drop Simplicity">
    You can build complex API workflows using a drag-and-drop interface, making it accessible for both technical and non-technical audience.
  </Step>

  <Step title="Visual REST API Integration">
    Specifically tailored for creating and managing REST API calls through a visual interface, streamlining the integration process without the need for extensive coding.
  </Step>

  <Step title="Real-Time Testing and Validation">
    Allows for immediate testing and validation of REST API calls within the design interface.
  </Step>
</Steps>

***

## Managing integration endpoints

### Data Sources

A data source is a collection of resources—endpoints, authentication, and variables—used to define and run integration workflows.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds1.png)
</Frame>

### Creating a new data source definition

With **Data Sources** feature you can create, update, and organize endpoints used in API integrations. These endpoints are integral to building workflows within the Integration Designer, offering flexibility and ease of use for managing connections between systems. Endpoints can be configured, tested, and reused across multiple workflows, streamlining the integration process.

<video />

Go to the **Data Sources** section in FlowX Designer at **Workspaces** -> **Your workspace** -> **Projects** -> **Your project** -> **Integrations** -> **Data Sources**.

<Info>
  The data sources resource page uses a tile-based creation flow and a unified details view.

  * **Creation modal**: clicking **New Data Source** opens a modal where each connector type appears as its own tile with an icon. Use the search box to filter tiles by name. Pick a tile, give the data source a name, and click **Create** to open the configuration page.
  * **List view**: each entry shows the connector's icon and type. Use the type filter at the top to scope the list to a specific connector (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.).
  * **Unified settings layout**: every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
  * **Save with incomplete configuration**: you can create and save a data source even when some fields (credentials, endpoints) are not yet available. The data source can be referenced in workflows and processes immediately, but it will only operate at runtime once required fields are filled in.
</Info>

### Data sources types

There are multiple types of data sources available:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds5.png)
</Frame>

<CardGroup>
  <Card title="RESTful System" icon="cloud">
    Connect to external REST APIs. Configure endpoints, authentication, and parameters for HTTP-based integrations. **Detailed in this document below.**
  </Card>

  <Card title="FlowX Database" icon="database" href="./flowx-database">
    Store and retrieve structured data within FlowX using MongoDB collections. Share data across processes without external dependencies.
  </Card>

  <Card title="Unmanaged MongoDB" icon="database" href="./unmanaged-mongodb">
    Connect to externally managed MongoDB instances. Use your existing MongoDB infrastructure with the same CRUD operations as FlowX Database.
  </Card>

  <Card title="MCP Integration" icon="plug" href="./mcp-integration/mcp-integration-overview">
    Connect Model Context Protocol servers to enable AI agents to use external tools, databases, and services.
  </Card>

  <Card title="FlowX Knowledge Base" icon="brain" href="./knowledge-base-integration/knowledge-base-overview">
    AI-powered contextual knowledge repositories for intelligent document search and retrieval in workflows.
  </Card>

  <Card title="Email Trigger" icon="envelope" href="./email-trigger">
    Start process instances automatically when emails are received. Connect to IMAP servers and monitor mailboxes for event-driven automation.
  </Card>

  <Card title="Email Sender" icon="paper-plane" href="./email-sender">
    Configure SMTP connections to send emails directly from processes, including replies to received emails.
  </Card>

  <Card title="Incoming Webhook" icon="webhook" href="./incoming-webhooks">
    Trigger processes from external systems via HTTP POST requests with API key authentication.
  </Card>
</CardGroup>

#### RESTful System

Add a **New Data Source**, set the data source's unique code, name, and description:

* **Select Data Source**: RESTful System
* **Name**: The data source's name.
* **Code**: A unique identifier for the external data source.
* **Base URL**: The base URL is the main address of a website or web application, typically consisting of the protocol (`http` or `https`), domain name, and a path.
* **Description**: A description of the data source and its purpose.
* **Enable enumeration value mapping**: If checked, this system will be listed under the mapped enumerations. See [enumerations](../core-extensions/content-management/enumerations) section for more details.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds6.png)
</Frame>

<Tip>
  To dynamically adjust the base URL based on the upper environment (e.g., dev, QA, stage), you can use environment variables and configuration parameters. For example: `https://api.${environment}.example.com/v1`.

  Additionally, keep in mind that the priority for determining the configuration parameter (e.g., base URL) follows this order: first, input from the user/process; second, configuration parameters overrides (set directly on FlowX.AI designer or environment variables); and lastly, configuration parameters.
</Tip>

2. Set up authorization (Service Token, Bearer Token, or No Auth). In our example, we will set the auth type as a bearer and we will set it at system level:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/auth_bearer_token.png)
</Frame>

<Tip>
  The value of the token might change depending on the environment so it is recommended to define it at system level and apply [Configuration Parameters Overrides](../../projects/runtime/configuration-parameters-overrides) at runtime.
</Tip>

### Defining REST integration endpoints

In this section you can define REST API endpoints that can be reused across different workflows.

1. Under the **Endpoints** section, add the necessary endpoints for system integration.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/add_new_endpoint.png)
</Frame>

2. Configure an endpoint by filling in the following properties:
   * **Method**: GET, POST, PUT, PATCH, DELETE.
   * **Path**: Path for the endpoint.
   * **Parameters**: Path, query, and header parameters.
   * **Content type** (POST endpoints): **JSON**, **Raw**, **Multipart/Form-Data**, or **Binary**.
   * **Response**: JSON or Single binary file.
   * **Response example**: Body or headers.

<Tip>
  **Sending non-JSON text bodies** (XML, SOAP, plain text, `application/x-www-form-urlencoded`): set the **Content type** to **Raw**. The body is sent as-is, and FlowX preserves the `Content-Type` you set in the endpoint's request **Headers** rather than forcing one. (Earlier releases offered only JSON, Multipart/form-data, or Binary, so these payloads had to be wrapped as multipart.)

  For OAuth token endpoints that expect a form-urlencoded payload (e.g. `client_credentials` or `password` grant), prefer configuring the data source's **Authorization** settings instead of building the call by hand — FlowX handles the token request internally and applies the resulting access token to subsequent calls.
</Tip>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds11.png)
</Frame>

### REST endpoint caching

For GET endpoints, you can configure response caching to reduce redundant API calls, avoid rate limits, and lower operational costs. When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.

#### Configuring cache Time-To-Live (TTL)

Choose between two TTL policies based on your use case:

<Tabs>
  <Tab title="Expires After (Duration-Based)">
    Cache responses for a specific duration after each request.

    **Configuration Options**:

    * **ISO Duration**: Use ISO 8601 duration format
      * `PT1H` - Cache for 1 hour
      * `PT30M` - Cache for 30 minutes
      * `P1D` - Cache for 1 day
      * `P1W` - Cache for 1 week
    * **Dynamic Duration**: Reference configuration parameters using `${myConfigParam}`
    * **Default**: `R/P1D` (1 day)

    **Use Case**: Ideal when you want consistent cache duration regardless of time of day.

    **Example**: Cache country list for 24 hours after each request

    ```
    P1D
    ```
  </Tab>

  <Tab title="Expires At (Time-Based)">
    Cache responses until a specific time with recurring patterns.

    **Configuration Options**:

    * **Expire Time**: Set the time when cache expires (format: `HH:MM`)
      * `00:00` - Midnight
      * `18:00` - 6 PM
      * `08:00` - 8 AM
    * **Recurrency**: How often the pattern repeats (integer > 0, default: 1)
    * **Time Unit**: Choose from Day, Week, or Month (default: Day)

    **Use Cases**:

    * Data that updates at specific times (e.g., daily reports at midnight)
    * Batch processes that refresh data on schedule
    * Business hours data that changes after 5 PM

    **Example 1**: Cache until midnight every day

    ```
    Expire Time: 00:00
    Recurrency: 1
    Time Unit: Day
    ```

    **Example 2**: Cache until 6 PM every Friday

    ```
    Expire Time: 18:00
    Recurrency: 1
    Time Unit: Week
    ```
  </Tab>
</Tabs>

#### Cache visibility and management

**Testing Modal**

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Test%20Endpoint.png)
</Frame>

When testing endpoints, you can view:

* **Cache Status**: Whether results came from cache (hit) or external API (miss)
* **Cache Key**: Unique identifier for the cached response
* **TTL Information**: When the cache will expire
  * Duration-based: "Expires after PT10M" (10 minutes)
  * Time-based: "Expires at 23:00 on 2025-11-04"

**Workflow Console**

Monitor cache usage during workflow execution with the same detailed information visible in logs.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Test%20Endpoint.png)
</Frame>

**Clear Cache**

Manually invalidate cached responses when needed:

* Available in the endpoint testing modal
* Available from the endpoint definition page
* Only visible when caching is configured

<Tip>
  Clear cache after updating data in the external system to ensure workflows fetch fresh data on the next request.
</Tip>

#### How caching works

<Steps>
  <Step title="First Request">
    When a GET endpoint is called for the first time, FlowX.AI:

    1. Calls the external API
    2. Stores the response in cache with the configured TTL
    3. Returns the response to the workflow
  </Step>

  <Step title="Subsequent Requests">
    If the cache is still valid (within TTL):

    1. FlowX.AI returns the cached response immediately
    2. No external API call is made
    3. Response time is significantly faster
  </Step>

  <Step title="Cache Expiration">
    Once the TTL expires:

    1. Next request fetches fresh data from the external API
    2. Cache is updated with the new response
    3. New TTL period begins
  </Step>
</Steps>

#### Error handling

<Warning>
  **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. Your workflows always receive correct data.
</Warning>

Automatic fallback scenarios:

* Cache service unavailable → Direct API call
* Cache corruption or invalid data → Direct API call
* Cache storage failure → Direct API call (with warning logged)

#### Use cases

<CardGroup>
  <Card title="Reference Data" icon="list">
    Cache country lists, product catalogs, currency rates, or other reference data that changes infrequently
  </Card>

  <Card title="Rate Limit Compliance" icon="gauge-max">
    Stay within third-party API rate limits by reducing the number of requests
  </Card>

  <Card title="Cost Optimization" icon="coins">
    Lower operational costs by reducing billable API calls to external services
  </Card>

  <Card title="Performance" icon="bolt">
    Improve workflow execution speed by eliminating network latency for cached responses
  </Card>
</CardGroup>

**Example**: An e-commerce platform caches product catalog data for 1 hour. With 1000 workflow executions per hour, caching reduces API calls from 1000 to just 1, saving 999 external calls while ensuring data freshness every hour.

### SQL operation caching

SQL data source operations support response caching with the same TTL policies as REST endpoints. On a SQL operation's details page, open the **Response Caching** section and toggle **Caching Enabled**, then choose a return policy (**Expires After** duration or **Expires At** time-based), exactly as for REST GET endpoints above. A **Clear cache** button invalidates cached responses on demand.

Caching is governed by three platform-wide settings on the `integration-designer` service:

| Environment Variable                | Description                                                                                                          | Default   |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------- |
| `FLOWX_SQL_CACHE_ENABLED`           | Global master switch for SQL operation caching. When `false`, per-operation caching is skipped and queries run live. | `true`    |
| `FLOWX_SQL_CACHE_MAX_PAYLOAD_BYTES` | Maximum size of a cacheable result payload                                                                           | `5242880` |
| `FLOWX_SQL_CACHE_MAX_DURATION`      | Upper bound on the cache duration a single operation can request                                                     | `PT24H`   |

<Note>
  Per-operation caching only takes effect when `FLOWX_SQL_CACHE_ENABLED` is `true`. If an operation has caching enabled while the global switch is off, the query runs live and a warning is logged.
</Note>

### Defining variables

The Variables tab allows you to store system-specific variables that can be referenced throughout workflows using the format `${variableName}`.

These declared variables can be utilized not only in workflows but also in other sections, such as the Endpoint or Authorization tabs.

<Tip>
  For example:

  * For our integration example, you can declare configuration parameters and use the variables to store your `tableId` and `baseId` and reference them the **Variables** tab.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds10.png)
  </Frame>

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds8.png)
  </Frame>

  * Use variables in the **Base URL** to switch between different environments, such as UAT or production.
</Tip>

### Endpoint parameter types

When configuring endpoints, several parameter types help define how the endpoint interacts with external systems. These parameters ensure that requests are properly formatted and data is correctly passed.

#### Path parameters

Elements embedded directly within the URL path of an API request that acts as a placeholder for specific value.

* Used to specify variable parts of the endpoint URL.
* Defined with `${parameter}` format.
* Mandatory in the request URL.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds15.png)
</Frame>

<Tip>
  Path parameters must always be included, while query and header parameters are optional but can be set as required based on the endpoint's design.
</Tip>

#### Query parameters

Query parameters are added to the end of a URL to provide extra information to a web server when making requests.

* Query parameters are appended to the URL after a `?` symbol and are typically used for filtering or pagination (for example, `?search=value`)
* Useful for filtering or pagination.
* Example URL with query parameters: [https://api.example.com/users?search=johndoe\&page=2](https://api.example.com/users?search=johndoe\&page=2).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds13.png)
</Frame>

<Warning>
  These parameters must be defined in the Parameters table, not directly in the endpoint path.
</Warning>

##### URL encoding option

Each query parameter has an **Encode** option that controls whether the value is URL-encoded before being sent:

* **Encode enabled**: The system automatically URL-encodes the parameter value (special characters like spaces, `&`, `=` are converted to their encoded equivalents like `%20`, `%26`, `%3D`)
* **Encode disabled** (default): The value is sent as-is, allowing you to provide pre-encoded values

<Tip>
  Use the **Encode** option when your parameter values may contain special characters that need encoding. Disable it if you're already providing URL-encoded values or if the external API expects raw values.
</Tip>

<Info>
  To preview how query parameters are sent in the request, you can use the **Preview** feature to see the exact request in cURL format. This shows the complete URL, including query parameters.
</Info>

#### Header parameters

Used to give information about the request and to give instructions to the API of how to handle the request

* Header parameters (HTTP headers) provide extra details about the request or its message body.
* They are not part of the URL. Default values can be set for testing and overridden in the workflow.
* Custom headers sent with the request (for example, `Authorization: Bearer token`).
* Define metadata or authorization details.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds14.png)
</Frame>

#### Body parameters

The data sent to the server when an API request is made.

* These are the data fields included in the body of a request, usually in JSON format.
* Body parameters are used in POST, PUT, and PATCH requests to send data to the external system (for example, creating or updating a resource).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds16.png)
</Frame>

#### Response body parameters

The data sent back from the server after an API request is made.

* These parameters are part of the response returned by the external system after a request is processed. They contain the data that the system sends back.
* Typically returned in GET, POST, PUT, and PATCH requests. Response body parameters provide details about the result of the request (for example, confirmation of resource creation, or data retrieval)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/response_body_param.png)
</Frame>

### Enum mapper

The enum mapper for the request body enables you to configure enumerations for specific keys in the request body, aligning them with values from the External System or translations into another language.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/enum_mapper.png)
</Frame>

On enumerations you can map both translation values from different languages or values for different source systems.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-10-27%20at%2012.42.28.png)
</Frame>

Make sure you have the enumerations created with corresponding translations and system values in your application already:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-10-27%2012.41.08.gif)
</Frame>

<Info>
  Select whether to use in the integration the enumeration value corresponding to the External System or the translation into another language.

  For translating into language a header parameter called 'Language' is required to specify the language for translation.
</Info>

### Configuring authorization

* Select the required **Authorization Type** from a predefined list.
* Enter the relevant details based on the selected type (for example, Realm and Client ID for Service Accounts).
* These details will be automatically included in the request headers when the integration is executed.

### Authorization methods

The Integration Designer supports several authorization methods, allowing you to configure the security settings for API calls. Depending on the external system's requirements, you can choose one of the following authorization formats:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/auth_type.png)
</Frame>

#### Service account

Service Account authentication requires the following key fields:

* **Identity Provider Url**: The URL for the identity provider responsible for authenticating the service account.
* **Client Id**: The unique identifier for the client within the realm.
* **Client secret**: A secure secret used to authenticate the client alongside the Client ID.
* **Scope**: Specifies the access level or permissions for the service account.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/auth_service_account.png)
</Frame>

<Info>
  When using Entra as an authentication solution, the **Scope** parameter is mandatory. Ensure it is defined correctly in the authorization settings.
</Info>

#### Basic authentication

* Requires the following credentials:
  * **Username**: The account's username.
  * **Password**: The account's password.
    * Suitable for systems that rely on simple username/password combinations for access.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/basic_auth.png)
</Frame>

#### Bearer

* Requires an **Access Token** to be included in the request headers.
* Commonly used for OAuth 2.0 implementations.
* Header Configuration: Use the format `Authorization: Bearer {access_token}` in headers of requests needing authentication.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/token_bearer.png)
</Frame>

* System-Level Example: You can store the Bearer token at the system level, as shown in the example below, ensuring it's applied automatically to future API calls:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/bearer.png)
</Frame>

<Tip>
  Store tokens in a configuration parameter so updates propagate across all requests when tokens are refreshed or changed.
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/token_config_param.png)
</Tip>

#### Certificates

Use this setup to configure secure communication with external systems that require certificates. It includes a Keystore (which holds the client certificate) and a Truststore (which holds trusted certificates). You can toggle these features based on the security requirements of the integration.

<Frame>
  ![Authorization tab showing certificates, truststore, and proxy configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/authorization_rest_all.png)
</Frame>

When the **Use Certificate** option is turned on, select a **Certificate type**:

* **Base64** (default for new configurations) — provide the certificate content directly as a base64-encoded string
* **Path** — provide the file system path to the certificate file

**Keystore credentials**

| Field                         | Base64 mode                     | Path mode                                             |
| ----------------------------- | ------------------------------- | ----------------------------------------------------- |
| **Keystore Content (Base64)** | Base64-encoded keystore content | —                                                     |
| **Keystore Path**             | —                               | File path, e.g., `/opt/certificates/testkeystore.jks` |
| **Keystore Password**         | Password to unlock the keystore | Password to unlock the keystore                       |
| **Keystore Type**             | `JKS` or `PKCS12`               | `JKS` or `PKCS12`                                     |

**Truststore credentials**

| Field                           | Base64 mode                       | Path mode                                               |
| ------------------------------- | --------------------------------- | ------------------------------------------------------- |
| **Truststore Content (Base64)** | Base64-encoded truststore content | —                                                       |
| **Truststore Path**             | —                                 | File path, e.g., `/opt/certificates/testtruststore.jks` |
| **Truststore Password**         | Password to access the truststore | Password to access the truststore                       |

All fields support `${configParam}` placeholders for dynamic per-environment resolution.

<Tip>
  Use [Configuration Parameters Overrides](../../projects/runtime/configuration-parameters-overrides) to manage certificate content and passwords across environments (Dev, UAT, Production) without changing the data source configuration. For example, store the base64 keystore content in a config parameter and reference it with `${keystoreContent}`.
</Tip>

<Frame>
  ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
</Frame>

***

## File handling

You can now handle file uploads and downloads with external systems directly within Integration Designer. This update introduces native support for file transfers in RESTful connectors, reducing the need for custom development and complex workarounds.

<Warning>
  **Important: Document replacement behavior**

  When saving files to the Document Plugin, if you upload a file with the **same `customId` AND `documentType` combination** as an existing document, the previous document will be automatically **marked as deleted** and replaced by the new file.

  This means:

  * The previous file's URLs will stop working
  * Only the most recent file with that `customId` + `documentType` combination will be accessible

  **Best practices:**

  * Always use **unique, dynamic values** for `customId` (for example, `${processInstanceId}`, `${clientId}`, `${uuid}`)
  * Never copy examples with hardcoded values like `customId: "1234"` or `documentType: "BULK"` without changing them
  * If you need to store multiple documents of the same type, ensure each has a unique `customId`

  ```json Example: Using dynamic customId theme={"system"}
  {
    "customId": "${processInstanceId}_${timestamp}",
    "documentType": "CONTRACT"
  }
  ```
</Warning>

### Core scenarios

Integration Designer supports two primary file handling scenarios:

<Steps>
  <Step title="Downloading Files">
    Can call an external API (`GET` or `POST`) and receives a response containing one or more files. Integration Designer saves these files to a specified location and returns their new paths to the workflow for further processing.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh1.png)
    </Frame>
  </Step>

  <Step title="Uploading Files">
    Can send a file that is already stored in the **Document Plugin** or a custom **S3 Bucket** to an external API via a `POST` request. The workflow transmits the file path, enabling file transfer without manual handling.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh2.png)
    </Frame>
  </Step>
</Steps>

<Info>
  Common use cases include contract generation workflows where data is sent to external document services and the generated files are retrieved back into the process.
</Info>

***

### Receiving XML and SOAP responses

<Info>
  **Available starting with FlowX.AI 5.9.0**

  Earlier releases assumed every response body was JSON — any other format failed the node even on a valid `2xx`. From 5.9.0, the engine honours the content type the endpoint declares and parses XML responses automatically.
</Info>

REST endpoints can consume **JSON**, **XML** (including **SOAP** envelopes), and **plain text** responses. You don't pick the response format in a dropdown — the engine resolves it from the endpoint's request **Headers**:

1. The **`Accept`** header wins (what the integration expects back).
2. If `Accept` is absent, the request **`Content-Type`** is used as a fallback.
3. If neither is set, the engine runs in **automatic** mode and infers the format from the upstream's response `Content-Type`.
4. Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) are treated as automatic — they don't commit to a format.

Media types are categorised as follows:

| Declared / received type                                                               | Parsed as | Resulting body                              |
| -------------------------------------------------------------------------------------- | --------- | ------------------------------------------- |
| `application/json`, `application/hal+json`, anything ending in `+json`                 | JSON      | Object you map with `${...}` paths          |
| `application/xml`, `text/xml`, anything ending in `+xml` (e.g. `application/soap+xml`) | XML       | Object you map the same way as JSON         |
| `text/*` (plain text, HTML)                                                            | Text      | The raw string                              |
| Anything else / unset                                                                  | Automatic | JSON if parseable, otherwise the raw string |

When an XML or SOAP response is parsed, you map its fields exactly like a JSON response (for example `${response.body.Envelope.Body.result}`). The original XML is preserved alongside the parsed object, so flows that need the raw markup can still access it.

<Warning>
  The engine fails the node with a clear error when the response does not match what the endpoint declared:

  * **Content type mismatch** — declared `application/json` but the upstream returned `text/plain`: `Expected response content type "application/json" but received "text/plain".`
  * **Parse failure on a declared type** — declared XML but the body is malformed: `Response declared as XML but could not be parsed as XML.`

  In automatic mode (or when XML was only *inferred* from the upstream's `Content-Type`), a parse failure does **not** fail the node — the raw string is returned instead, so a mislabelled upstream doesn't break the flow.
</Warning>

XML parsing is XXE-safe: external entity resolution and DTD processing are disabled, so XXE and entity-expansion payloads cannot read local files or exhaust memory.

XML bodies larger than 5 MiB are returned as raw strings without parsing.

<Note>
  To **send** a SOAP or XML request body, set the endpoint **Content type** to **Raw** and add the matching `Content-Type` header — see [Defining REST integration endpoints](#defining-rest-integration-endpoints) above.
</Note>

***

### Receiving files (endpoint response configuration)

To configure an endpoint to handle incoming files from an external system, navigate to its **Response** tab. This functionality is available for both `GET` and `POST` methods.

#### Enabling and configuring file downloads

<Steps>
  <Step title="Activate File Processing">
    Switch the **Save Files** toggle to the "on" position to activate file processing for the response.

    <Warning>
      If this toggle is **off**, the system will not process files. A `Single Binary` response will result in an error, and a `JSON` response with Base64 data will be passed through as a raw string.
    </Warning>
  </Step>

  <Step title="Configure Content-Type">
    Select the expected format of the successful API response from the **Content-Type** dropdown:

    * `JSON` (Default): For responses containing Base64 encoded file data
    * `Single Binary`: For responses where the body is the file itself
  </Step>
</Steps>

#### Handling JSON content-type

This option is used when the API returns a JSON object containing one or more Base64 encoded files.

**File Destination Configuration:**

<Tabs>
  <Tab title="Document Plugin">
    Saves files to the platform's managed storage, linking them to a specific process instance. The Document Plugin acts as a wrapper over the file system and provides special integration capabilities with document templates.

    <ParamField type="string">
      The ID of the process instance. This field defaults to `${processInstanceId}` to be mapped dynamically at runtime.
    </ParamField>

    <Tip>
      When using Document Plugin for file operations, you typically send only the document reference (ID) rather than the entire file content. The Integration Designer handles the special integration with document templates automatically.
    </Tip>

    **Files Mapping Table:**

    | Column                | Description                                                 | Example            |
    | --------------------- | ----------------------------------------------------------- | ------------------ |
    | **Base 64 File Key**  | The JSON path to the Base64 encoded string                  | `files.user.photo` |
    | **File Name Key**     | *Optional.* The JSON path to the filename string            | `files.photoName`  |
    | **Default File Name** | A fallback name to use if the File Name Key is not found    | `imagineProfil`    |
    | **Default Folder**    | The business-context folder, such as a client ID (`CNP`)    | `folder_client`    |
    | **Default Doc Type**  | The document type for classification in the Document Plugin | `Carte Identitate` |
  </Tab>

  <Tab title="S3 Protocol">
    Saves files to a custom S3 bucket, ideal for files not tied to a specific process instance or when Document Plugin is not available.

    This configuration requires the same **Files** table but omits the `Process Instance` and `Default Document Type` fields since S3 storage operates independently of the FlowX document management system.

    <Tip>
      Use S3 Protocol when you want to manipulate files at the workflow level for scenarios like AI processing, report generation, or CMS integrations with unassociated documents.
    </Tip>
  </Tab>
</Tabs>

<Info>
  The `Translate or Convert Enumeration Values` toggle can be used in conjunction with the `Save Files` feature.
</Info>

#### Handling Single Binary content-type

This option is used when the entire API response body is the file itself. The Single Binary content-type is ideal for endpoints that return raw file data directly in the response body.

<Steps>
  <Step title="Configure Content-Type">
    In the **Response** tab of your endpoint configuration:

    1. Enable the **Save Files** toggle
    2. Select **Single Binary** from the **Content-Type** dropdown

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh3.png)
    </Frame>

    <Warning>
      If the **Save Files** toggle is disabled, attempting to handle a Single Binary response will result in an error.
    </Warning>
  </Step>

  <Step title="Choose File Destination">
    Select your preferred file storage destination:

    <Tabs>
      <Tab title="S3 Protocol">
        For files stored in custom S3 buckets, ideal for files not tied to specific process instances.
      </Tab>

      <Tab title="Document Plugin">
        For files managed by FlowX's document system, linked to process instances with additional metadata.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure File Name Identification">
    Choose how the system should identify the filename from the response.
  </Step>
</Steps>

**File Name Identification Methods:**

<Tabs>
  <Tab title="Auto Identify (Recommended)">
    The system automatically parses the `Content-Disposition` HTTP header to extract the `filename` attribute. This is the standard approach for most file download endpoints.

    <Check>
      **When to use:** When the external API follows standard HTTP conventions and includes file information in the `Content-Disposition` header.
    </Check>

    **Example of standard Content-Disposition header:**

    ```
    Content-Disposition: attachment; filename="document.pdf"
    ```

    The system will automatically extract `document.pdf` as the filename.
  </Tab>

  <Tab title="Manual Configuration">
    Configure custom header parsing when the external system doesn't follow standard conventions or uses custom headers for file information.

    <Steps>
      <Step title="Disable Auto Identify">
        Turn off the **Auto Identify File** toggle to enable manual configuration options.
      </Step>

      <Step title="Configure Header Fields">
        <ParamField type="string">
          The name of the HTTP header that contains the filename information.

          **Examples:**

          * `X-Dctm-Object-Name`
          * `X-File-Name`
          * `Custom-Filename-Header`
        </ParamField>

        <ParamField type="string">
          The specific attribute or value within the header to extract as the filename.

          **Examples:**

          * For simple headers: leave empty or use the full header value
          * For complex headers: specify the attribute name
        </ParamField>
      </Step>

      <Step title="Apply Custom Regex (Optional)">
        Enable the **Apply Custom Regex** toggle when you need to extract the filename using pattern matching.

        <Info>
          **When to use regex:** When the filename is embedded within a larger header value and needs to be extracted using pattern matching.

          **Example scenarios:**

          * Header value: `filename=document.pdf; size=1024`
          * Regex pattern: `filename=([^;]+)`
          * Extracted result: `document.pdf`
        </Info>

        **Common regex patterns:**

        ```regex theme={"system"}
        # Extract filename from "filename=document.pdf"
        filename=(.+)

        # Extract filename with extension from complex header
        ([a-zA-Z0-9_-]+\.[a-zA-Z]{2,4})

        # Extract quoted filename: filename="my document.pdf"
        filename="([^"]+)"
        ```
      </Step>
    </Steps>

    <Tip>
      Use manual configuration when working with legacy systems, custom APIs, or when the external server provides file information through non-standard headers.
    </Tip>
  </Tab>
</Tabs>

**File Destination Configuration:**

<Tabs>
  <Tab title="Document Plugin">
    For files managed within FlowX's document system with full process integration:

    <ParamField type="string">
      Fallback filename if header extraction fails
    </ParamField>

    <ParamField type="string">
      Business context folder (e.g., client ID, case number)
    </ParamField>

    <ParamField type="string">
      Document classification for the Document Plugin
    </ParamField>

    <Info>
      Files stored via Document Plugin are automatically linked to process instances and can be used with document templates and other FlowX document features.
    </Info>
  </Tab>

  <Tab title="S3 Protocol">
    For files stored in custom S3 buckets with flexible storage options:

    <ParamField type="string">
      Fallback filename if header extraction fails
    </ParamField>

    <ParamField type="string">
      Optional folder structure within the S3 bucket
    </ParamField>

    <Tip>
      S3 Protocol storage is ideal for files that need to be processed by external systems, used in AI workflows, or when Document Plugin is not available.
    </Tip>
  </Tab>
</Tabs>

**Configuration Examples:**

<CodeGroup>
  ```json Auto Identify Example theme={"system"}
  {
    "contentType": "Single Binary",
    "saveFiles": true,
    "autoIdentifyFile": true,
    "fileDestination": "S3 Protocol",
    "defaultFileName": "downloaded_file",
    "defaultFolder": "client_${clientId}"
  }
  ```

  ```json Manual Configuration Example theme={"system"}
  {
    "contentType": "Single Binary", 
    "saveFiles": true,
    "autoIdentifyFile": false,
    "fileNameHeaderKey": "X-Document-Name",
    "fileNameHeaderAttribute": "filename",
    "applyCustomRegex": true,
    "customRegex": "filename=\"([^\"]+)\"",
    "fileDestination": "Document Plugin",
    "defaultFileName": "fallback_document",
    "defaultFolder": "documents",
    "defaultDocumentType": "Contract",
  }
  ```
</CodeGroup>

***

### Sending files (endpoint POST body configuration)

To configure an endpoint to send a file, navigate to the **Body** tab and select the appropriate **Content Type**.

#### Content Type: Multipart/Form-data

Use this to send files and text fields in a single request. This format is flexible and can handle mixed content types within the same POST request.

<Steps>
  <Step title="Configure File Source">
    Select where the file originates:

    * `Document Plugin`
    * `S3 Protocol`
  </Step>

  <Step title="Define Form Parts">
    Add rows to the resource table, defining each part of the form:

    * **Key Type**: Choose `File` or `Text`
    * **Value**:
      * For files: Provide the `filePath` (Minio path for S3 or Document Plugin reference)
      * For text: Provide the string value or variable reference

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh4.png)
    </Frame>
  </Step>
</Steps>

<Info>
  Multipart requests can be sent even without files - you can include only text fields by setting all Key Types to `Text`. The difference between content types is primarily in how data is packaged for transmission to the target server.
</Info>

#### Content Type: Single binary

Use this to send the raw file as the entire request body. This method sends only the file content without any additional form data or metadata.

<ParamField type="string">
  Select `Document Plugin` or `S3 Protocol`
</ParamField>

<ParamField type="string">
  Specify the path of the file to be sent (Minio path for the file location)
</ParamField>

<Tip>
  When using Single Binary, only the Minio path is required since the entire request body will be the file content itself, without any additional packaging or metadata.
</Tip>

#### Content Type: JSON

<Warning>
  This option should be used for standard JSON payloads **only**. It does not support embedding files for uploads; use `Multipart/Form-Data` or `Single Binary` for that purpose.
</Warning>

***

### Runtime behavior & testing

#### Workflow node configuration

All configured file settings (for example, `File Path`, `Folder`, `Process Instance ID`) are exposed as parameters on the corresponding workflow nodes, allowing them to be set dynamically using process variables at runtime.

#### Response payload & logging

<Check>
  When a node successfully downloads and saves a file, its output will contain the **`filePath`** to the stored file, **not** the raw Base64 string or binary content.
</Check>

<Info>
  For security and performance, runtime logs will also only contain the `filePath`, not the raw file content.
</Info>

#### Error handling

If a node is configured to receive a `Single Binary` file but the external system returns a `JSON` error (for example, file not found), the JSON error will be correctly passed through to the workflow for handling.

#### Testing guidelines

<Tip>
  The **Test Modal** is context-aware. It will only display input fields for file parameters (`Process Instance ID`, `Folder`, etc.) if `Save Files` is enabled on the endpoint.
</Tip>

<Warning>
  If you test an endpoint that returns a binary file without configuring it as `Single Binary`, the test will fail with the error: "*Endpoint returns a binary file. Please configure the Content-Type to handle binary responses.*"
</Warning>

<Info>
  The **Response Example** tab is now separate from the **Response** configuration tab and includes both `Body` and `Headers` sections for better clarity.
</Info>

### Example: sending files to an external system after uploading a file to the Document Plugin

<Info>
  In this example, we'll send a file to an external system using the  Integration Designer.
</Info>

<Steps>
  <Step title="Upload a file to the Document Plugin">
    Configure a process where you will upload a file to the Document Plugin.

    * Configure a User Task node where you will upload the file to the Document Plugin.
    * Configure an Upload File Action node to upload the file to the Document Plugin.
    * Configure a Save Data Action node to save the file to the Document Plugin.
  </Step>

  <Step title="Configure the Integration Designer">
    Configure the Integration Designer to send the file to an external system:

    * Configure a REST Endpoint node to send the file to an external system.
  </Step>
</Steps>

***

## Workflows

A workflow defines a series of tasks and processes to automate system integrations. Within the Integration Designer, workflows can be configured using different components to ensure efficient data exchange and process orchestration.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/workflow_ex.png)
</Frame>

### Creating a workflow

1. Navigate to Workflow Designer:
   * In FlowX.AI Designer to **Projects -> Your application -> Integrations -> Workflows**.
   * Create a New Workflow, provide a name and description, and save it.
2. Start to design your workflow by adding nodes to represent the steps of your workflow:

* **Start Node**: Defines where the workflow begins and also defines the input parameter for subsequent nodes.
* **REST endpoint nodes**: Add REST API calls for fetching or sending data.
* **FlowX Database nodes**: Read and write data to FlowX Database collections.
* **Custom Agent nodes**: Enable AI agents to use MCP tools for intelligent task automation.
* **Intent Classification nodes**: Classify user messages using AI and route the workflow to the matching intent branch.
* **Context Retrieval nodes**: Perform RAG searches against Knowledge Bases to retrieve relevant chunks without calling an LLM.
* **Parallel workflow execution**: Execute multiple workflow branches concurrently to improve performance and reduce total execution time.
* **Fork nodes (conditions)**: Add conditional logic for decision-making.
* **Data mapping nodes (scripts)**: Write custom scripts in JavaScript or Python.
* **Subworkflow nodes**: Invoke other workflows as reusable components.
* **Navigate in UI Flow nodes**: Navigate users to specific UI Flow screens from conversational workflows, passing dynamic parameters.
* **Web Page Extractor nodes**: Crawl web pages, follow links up to a configurable depth, and extract content for use in workflows or Knowledge Bases.
* **End Nodes**: Capture output data as the completed workflow result, ensuring the process concludes with all required information.
* **Update Knowledge Base**: Update the Knowledge Base with the results of the workflow.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/create_workflow.gif)
</Frame>

### Workflow nodes overview

<Info>
  Workflow nodes are the building blocks of your integration logic. Each node type serves a specific function, allowing you to design, automate, and orchestrate complex processes visually.
</Info>

| Node Type                   | Purpose                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| Start Node                  | Defines workflow input and initializes data                                                            |
| REST Endpoint Node          | Makes REST API calls to external systems                                                               |
| FlowX Database Node         | Reads/writes data to the FlowX Database                                                                |
| Custom Agent Node           | Enables AI agents to use MCP tools for intelligent automation                                          |
| Intent Classification Node  | Classifies user messages using AI and routes to matching intent branches                               |
| Context Retrieval Node      | Retrieves relevant data from Knowledge Bases or memory using semantic, keyword, or hybrid search       |
| AI Nodes                    | Process text, documents, images, and data using AI-powered capabilities                                |
| Condition (Fork)            | Adds conditional logic and parallel branches                                                           |
| Script Node                 | Transforms or maps data using JavaScript or Python                                                     |
| Update Knowledge Base       | Update the Knowledge Base with the results of the workflow                                             |
| Subworkflow Node            | Invokes another workflow as a modular, reusable subcomponent                                           |
| Navigate in UI Flow         | Navigates the user to a specific screen in a UI Flow from a conversational workflow                    |
| Web Page Extractor          | Crawls web pages, follows links up to a configurable depth, and extracts content                       |
| End Node                    | Captures and outputs the final result of the workflow                                                  |
| Parallel Workflow Execution | Execute multiple workflow branches concurrently to improve performance and reduce total execution time |

***

### Workflow data models

Workflow Data Models bring structured data management to Integration Designer workflows, enabling you to define input and output parameters at the workflow level, similar to Process Data Models.

#### Key benefits

<CardGroup>
  <Card title="Automatic Input Management" icon="wand-magic-sparkles">
    Input parameters automatically pre-fill the Start Node from the data model—no manual JSON editing
  </Card>

  <Card title="Consistent Data Lineage" icon="timeline">
    Ensure data consistency across processes and workflows with structured data models
  </Card>

  <Card title="Type Safety" icon="shield-check">
    Define data types and validation rules at the workflow level for runtime safety
  </Card>

  <Card title="Better Integration" icon="link">
    Map data bidirectionally between processes and workflows using data mappers
  </Card>
</CardGroup>

#### Quick start

<Steps>
  <Step title="Define Data Model">
    Create entities and attributes for your workflow data structure
  </Step>

  <Step title="Configure Input Parameters">
    Select which attributes will be workflow input parameters
  </Step>

  <Step title="Automatic Pre-fill">
    Start Node is automatically populated with structured data from your data model
  </Step>

  <Step title="Map to Processes">
    Use data mappers to pass data between processes and workflows
  </Step>
</Steps>

<Card title="Complete Workflow Data Models Guide" href="./workflow-data-models" icon="book-open">
  Learn how to create workflow data models, configure input/output parameters, and integrate with processes
</Card>

***

### Start node

The Start node is the mandatory first node in any workflow. It defines the input data model and passes this data to subsequent nodes.

<Tip>
  Define all required input fields in the Start node to ensure data mapping from processes or user tasks.
</Tip>

<Info>
  Use [Workflow Data Models](./workflow-data-models) to define structured input and output parameters at the workflow level. Input parameters automatically pre-fill the Start Node from the data model.
</Info>

***

### REST endpoint node

Enables communication with external systems via REST API calls. Supports GET, POST, PUT, PATCH, and DELETE methods. Endpoints are selected from a dropdown, grouped by system.

* **Params**: Configure path, query, and header parameters.
* **Input/Output**: Input is auto-populated from the previous node; output displays the API response.

<Tip>
  You can test REST endpoint nodes independently to validate connections and data retrieval.
</Tip>

***

### FlowX database node

Allows you to read and write data to the FlowX Database within your workflow.

<Card title="FlowX Database Documentation" icon="database" href="./flowx-database">
  Learn more about FlowX Database operations, collections, and usage
</Card>

***

### Context Retrieval node

Retrieves relevant data from Knowledge Bases or conversation memory using semantic and keyword search. Available under **Data Operations** in the workflow node palette.

**Configuration:**

* **Source** — choose between Knowledge Base or Memory (Memory is available only in conversational workflows)
* **Knowledge Base** — select a Knowledge Base to search (when source is Knowledge Base)
* **User Query** — the search query, supports process variable expressions (e.g., `${userMessage}`)
* **Search Type** — Hybrid (default), Semantic, or Keywords
* **Max Number of Chunks** — how many chunks to return (1-10, default: 5)
* **Min Relevance Score** — minimum relevance threshold (0-100%, default: 70%)
* **Metadata Filters** — filter chunks by metadata properties using the query builder: typed operators per key type and AND/OR grouping
* **Use advance metadata filters** — toggle to enable expression-based filtering for complex logic
* **Use Re-rank** — toggle to re-rank retrieved chunks before returning

<Card title="Using Knowledge Base in Workflows" icon="book-open" href="./knowledge-base-integration/using-knowledge-base-in-workflows">
  Learn how to configure Context Retrieval and Custom Agent nodes with Knowledge Bases
</Card>

***

### Custom Agent node

Enables AI agents to perform intelligent, autonomous tasks using Model Context Protocol (MCP) tools within your workflow. Custom Agent nodes apply ReAct (Reasoning and Acting) to decide which tools to use and execute multi-step operations.

**Key capabilities:**

* Access external systems through MCP servers
* Execute complex, multi-step operations autonomously
* Make intelligent decisions based on available tools
* Return structured responses for downstream processing

**Use cases:**

* Customer support automation with CRM integration
* Data analysis across multiple systems
* Dynamic integration orchestration
* Autonomous problem-solving workflows

<Card title="Custom Agent Node Documentation" icon="robot" href="./custom-agent-node">
  Learn how to configure Custom Agent nodes, write effective prompts, and monitor AI agent execution
</Card>

***

### Intent Classification node

Classifies user messages using an LLM and automatically routes the workflow to the matching intent branch — combining AI classification and conditional branching in a single node. Works like a [Condition (Fork)](#condition-fork-node) node, but uses natural language intent descriptions instead of code expressions.

**Key capabilities:**

* Define up to 10 intents as plain-text descriptions
* Automatic "If No Intent Matches" fallback branch
* Optional conversation memory for context-aware classification
* Optional rationale output explaining the classification decision

**Common use cases:**

* Chatbot message routing
* Email triage and classification
* Customer support ticket categorization

<Card title="Intent Classification Documentation" icon="arrows-split-up-and-left" href="/5.9/ai-platform/agent-builder/intent-classification">
  Learn how to configure intents, output format, and routing behavior
</Card>

***

### Context Retrieval node

Performs a RAG (Retrieval-Augmented Generation) search against a Knowledge Base and returns relevant chunks — without calling an LLM. Use this node when you need to retrieve information from a Knowledge Base and pass it to downstream nodes for further processing.

**Key capabilities:**

* Query Knowledge Bases using semantic, keyword, or hybrid search
* Configure relevance thresholds and result limits
* Apply property-based filters to narrow results
* Optional re-ranking for improved result quality
* Returns structured chunk data (content, metadata, relevance score, store)

**Common use cases:**

* Feeding context into a downstream Custom Agent or Text Generation node
* Building multi-step RAG pipelines with custom processing between retrieval and generation
* Retrieving relevant documentation chunks for further analysis

<Card title="Context Retrieval Documentation" icon="magnifying-glass" href="/5.9/ai-platform/agent-builder/context-retrieval">
  Learn how to configure Context Retrieval nodes, search types, and output format
</Card>

***

### AI Nodes

AI nodes enable intelligent processing of text, documents, images, and data directly within your Integration Designer workflows.

<Frame>
  ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
</Frame>

#### AI Text Operations

| Node                    | Description                                                                      |
| ----------------------- | -------------------------------------------------------------------------------- |
| **Text Transformation** | Modify text tone, complexity or formatting for better clarity or style           |
| **Text Understanding**  | Analyze text to determine sentiment, topics, intent, language and named entities |
| **Text Generation**     | Generate new text such as summaries, completions, translations or paraphrases    |
| **Text Extraction**     | Extract structured information, keywords or metadata from text                   |

#### AI Document Operations

| Node                       | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| **Document Generation**    | Automatically build reports or complete templates based on given inputs           |
| **Document Extraction**    | Identify and extract structured data, entities or metadata from documents         |
| **Document Understanding** | Analyze documents to extract meaning, topics, sentiment, or important information |
| **Extract Data from File** | Extract text and data from documents and images using LLM, OCR, or text parsing   |

#### AI Image Operations

| Node                  | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| **Image Description** | Generate captions or extract detailed information from visual content         |
| **Image Analysis**    | Recognize objects, emotions and scenes in images for contextual understanding |

#### AI Data Operations

| Node                    | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| **Data Enrichment**     | Add annotations, context or relationships to enhance raw data value        |
| **Data Generation**     | Produce synthetic or structured data using templates and logic-based rules |
| **Data Transformation** | Clean, normalize, aggregate, or restructure datasets into usable formats   |

<Card title="AI Node Types" icon="brain" href="../../../ai-platform/agent-builder/node-types">
  Learn more about AI node types and configuration options
</Card>

#### Personal Information Guard

The Personal Information Guard is a configuration block on every AI workflow node. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations.

**Configuration**

| Field               | Description                                                                                                                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`           | Turn the guard on for the node.                                                                                                                                                                                                                                                       |
| `sensitivityPreset` | One of `STRICT`, `BALANCED`, `RELAXED`, `CUSTOM`. Maps to a server-side detection threshold; `CUSTOM` exposes the `customSensitivity` slider (0.00–1.00).                                                                                                                             |
| `customSensitivity` | Threshold value used when `sensitivityPreset = CUSTOM`.                                                                                                                                                                                                                               |
| `scanDirections`    | Set of `INPUT` and/or `OUTPUT`. Both can be enabled. Empty sets are rejected.                                                                                                                                                                                                         |
| `entityKeys`        | Entity types to detect (e.g., `EMAIL_ADDRESS`, `PHONE_NUMBER`, `IBAN_CODE`). The Designer modal groups them under three scopes: **Universal**, **Regional EN**, and **Regional RO**. The catalog is served from `GET /integration/api/workflows/personal-information-guard/entities`. |

**How it works**

* **Input scan** runs before the AI request is built, so placeholder substitution and the user-message extraction both see redacted data. The `systemPrompt` is scanned alongside inputs because operation-prompt templates may carry PII from earlier nodes.
* **Source-file scan** runs for document and image AI nodes. The Data Privacy service uploads the redacted artifact back to the same storage as the source (so `filePathForRequest` is swapped without changing the data source binding).
* **Output scan** runs after the LLM completes, on a bounded-elastic scheduler so the Data Privacy WebClient call does not pin the reactor-netty event loop.
* **System-prompt appender** — for Custom Agent nodes, the runner appends a non-editable segment teaching the LLM how to handle `<PII type=.../>` placeholders. The appender runs after the prompt scan so its literal tags are not mistaken for PII.
* **Fail-closed** — any error from the Data Privacy service stops execution. The error surfaces on the node run log; redacted artifacts are not produced on failure.

**Run-log fields**

Each enabled scan adds a `personalInformationGuard` block on the node response (`AiNodeResponseDetailsDTO`):

| Field                                        | Description                                                                                     |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `scanStatus`                                 | `COMPLETED`, `SKIPPED`, or `FAILED`.                                                            |
| `totalDetections`                            | Total number of entities detected across `detections`.                                          |
| `detections`                                 | List of per-entity detection items (see below). Empty when nothing was detected.                |
| `errorMessage`                               | Populated when `scanStatus = FAILED`.                                                           |
| `sourceType`                                 | `TEXT`, `DOCUMENT`, or `IMAGE`. Identifies what the scan ran against. Null for text-only scans. |
| `originalStoragePath`, `redactedStoragePath` | Set for `DOCUMENT` and `IMAGE` scans; both point at the data source bound to the node.          |

Each item in `detections` carries:

| Field           | Description                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| `entityKey`     | Entity type detected (e.g., `EMAIL_ADDRESS`, `PHONE_NUMBER`, `IBAN_CODE`).                                   |
| `confidence`    | Detector confidence score, `0.00`–`1.00`.                                                                    |
| `originalValue` | The exact substring that was matched in the source.                                                          |
| `replacement`   | The placeholder string that replaced `originalValue` before the LLM call.                                    |
| `direction`     | `INPUT` or `OUTPUT` — which scan direction produced this detection.                                          |
| `sourceType`    | `TEXT`, `DOCUMENT`, or `IMAGE` — matches the wrapper's `sourceType` and indicates which payload was scanned. |
| `timestamp`     | When the detection was made.                                                                                 |
| `regions`       | List of bounding boxes (`x`, `y`, `width`, `height`) for `DOCUMENT` and `IMAGE` detections. Null for `TEXT`. |

Document and image scans surface the same per-entity detail as text scans, so the run console shows the matched values, replacements, and confidences regardless of which AI node type produced them.

The Data Privacy service connection is configured by `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` in the [Integration Designer setup guide](../../../setup-guides/integration-designer-setup#service-communication).

***

### Condition (Fork) node

Evaluates logical conditions (JavaScript or Python) to direct workflow execution along different branches.

* **If/Else**: Routes based on condition evaluation.
* **Parallel Processing**: Supports multiple branches for concurrent execution.

<Info>
  Use fork nodes to implement business rules, error handling, or multi-path logic.
</Info>

#### Available bindings

Condition expressions have access to the following data bindings:

| Binding                                   | Description                                                                                                       |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `input`                                   | Workflow input data from the previous node                                                                        |
| `additionalData.securityDetails`          | Current user's identity (username, identifier, details including roles, groups, and attributes from 5.7.0 onward) |
| `additionalData.applicationConfiguration` | Configuration parameters from the app build                                                                       |

#### Condition examples

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    // Route based on user identity
    additionalData.securityDetails.username === 'admin@company.com'

    // Route based on configuration parameter
    additionalData.applicationConfiguration.featureEnabled === true

    // Combine input data with config parameters
    input.amount > additionalData.applicationConfiguration.approvalThreshold

    // Check user and input together
    input.priority === 'high' && additionalData.securityDetails.details.email.endsWith('@company.com')
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Route based on user identity
    additionalData["securityDetails"]["username"] == "admin@company.com"

    # Route based on configuration parameter
    additionalData["applicationConfiguration"]["featureEnabled"] == True

    # Combine input data with config parameters
    input["amount"] > additionalData["applicationConfiguration"]["approvalThreshold"]

    # Check user and input together
    input["priority"] == "high" and additionalData["securityDetails"]["details"]["email"].endswith("@company.com")
    ```
  </Tab>
</Tabs>

<Tip>
  For details on the `securityDetails` and `applicationConfiguration` structure, see [Extracting additional data in business rules](../../building-blocks/actions/business-rule-action/extracting-additional-data).
</Tip>

***

### Parallel workflow execution

<Card title="Parallel Workflows" icon="code-fork">
  Execute multiple workflow branches concurrently to improve performance and reduce total execution time. The Integration Designer supports parallel execution using Start Parallel and End Parallel nodes.
</Card>

<Frame>
  <video />
</Frame>

#### Key concepts

<CardGroup>
  <Card title="Start Parallel Node" icon="code-fork">
    Split workflow execution into multiple concurrent branches that run independently
  </Card>

  <Card title="End Parallel Node" icon="code-merge">
    Merge parallel branches back together, waiting for all branches to complete before continuing
  </Card>

  <Card title="Path Visualization" icon="diagram-project">
    Visual path indexing in the workflow diagram shows which nodes belong to which parallel branch
  </Card>

  <Card title="Runtime Monitoring" icon="clock">
    Track parallel path execution with timing information for each branch and merge points
  </Card>
</CardGroup>

#### How to use parallel workflows

<Steps>
  <Step title="Design Parallel Paths">
    Add a Start Parallel node and create multiple sequences from it, each representing an independent execution path
  </Step>

  <Step title="Configure Branch Logic">
    Add workflow nodes to each parallel branch - API calls, transformations, database operations, or any other node type
  </Step>

  <Step title="Merge Paths">
    Close parallel branches with an End Parallel node that waits for all branches to complete before continuing
  </Step>

  <Step title="Runtime Execution">
    At runtime, all branches execute concurrently. The End Parallel node completes when the slowest branch finishes
  </Step>
</Steps>

#### Use cases

<CardGroup>
  <Card title="Multiple API Calls" icon="cloud">
    Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
  </Card>

  <Card title="Data Enrichment" icon="database">
    Fetch data from multiple sources in parallel for comprehensive data aggregation
  </Card>

  <Card title="Notification Broadcasting" icon="bell">
    Send notifications through multiple channels (email, SMS, push) simultaneously
  </Card>

  <Card title="Document Processing" icon="file-lines">
    Process different document types or sections in parallel for faster throughput
  </Card>
</CardGroup>

#### Runtime behavior

<Accordion title="Data at fork (Start Parallel)">
  When the Start Parallel node executes, each branch receives a **deep copy** of the parent's data. Branches work on independent copies — changes in one branch do not affect another branch during execution.
</Accordion>

<Accordion title="Data merge at join (End Parallel)">
  When all branches complete, the End Parallel node merges each branch's changes back into the parent using a **recursive deep merge** with **last-write-wins** semantics:

  * Each branch's modified keys are merged into the parent data
  * If two branches modify **different keys**, both changes are preserved
  * If two branches modify the **same key**, the last branch to finish overwrites the earlier value
  * For **nested objects**, the merge is recursive — only conflicting leaf values are overwritten
  * For **arrays**, no element-level merge occurs — the entire array is replaced by the last branch's version

  Since merge order depends on which branch finishes last, avoid modifying the same keys in multiple branches. If branches must write to the same structure, use distinct keys per branch and merge them in a Script node after the End Parallel.
</Accordion>

<Accordion title="Path Timing">
  * **Path Time**: Sum of all node execution times within that branch
  * **End Parallel Time**: Node processing time + maximum time across all parallel paths
  * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
</Accordion>

<Accordion title="Console Logging">
  * **Start Parallel Node**: Displays Input tab showing data split across branches
  * **End Parallel Node**: Displays Output tab showing merged results from all branches
  * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
</Accordion>

<Accordion title="Error Handling">
  * If any branch fails, the workflow handles it according to standard error handling rules
  * The End Parallel node waits for all non-failed branches to complete before merging
  * If branches do not converge to the same End Parallel node, the workflow fails with a `Missing end parallel gateway` error
</Accordion>

#### Limitations and considerations

<Warning>
  Keep the following constraints in mind when designing parallel workflows:
</Warning>

* **Last-write-wins merge**: When multiple branches modify the same data key, the final value depends on which branch completes last. This is non-deterministic if branch durations vary. To preserve data from all branches, write to different keys and merge manually in a Script node after the End Parallel
* **Array handling**: Arrays are not merged element-by-element. The entire array is replaced by the last branch's version. You cannot process individual array elements in separate branches (e.g., first element in branch 1, second element in branch 2)
* **Branch closure**: All branches from a Start Parallel must converge to the **same** End Parallel node. The End Parallel node can have only one outgoing sequence
* **Nested parallel paths**: Start Parallel nodes can be nested inside other parallel branches for multi-level concurrency
* **No cross-branch dependencies**: Branches execute concurrently on independent data copies. One branch cannot read data written by another branch during execution

<Tip>
  Design parallel branches to write to **distinct keys** in the data model. For example, if calling three APIs in parallel, store results in `apiResultA`, `apiResultB`, and `apiResultC` rather than writing all results to the same `apiResult` key.
</Tip>

***

### Script node

Executes custom JavaScript or Python code to transform, map, or enrich data between nodes.

#### Testing a script in isolation

A Script node ships with a **Test modal** that lets you exercise the script against sample input without running the full workflow. Open it with the **expand** icon at the top-right corner of the code editor, next to the expand/collapse chevron.

The modal has three side-by-side panels:

| Panel      | Purpose                                                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Input**  | JSON input passed to the script. Load from a past individual node run or from a past workflow run via the input selector. |
| **Code**   | The script body. Inline warnings are surfaced as you type. Includes **Save** and **Test** buttons.                        |
| **Output** | The JSON returned by the script after running **Test**. Runtime errors are shown here.                                    |

<Tip>
  The **Test** button runs the current contents of the Code panel, even if you have not clicked **Save** yet. Use this to iterate on a fix without committing changes to the Script node.
</Tip>

<Note>
  Runs triggered from the Test modal are excluded from the Console log History panel, because they may be running unsaved code.
</Note>

#### Run instance IDs in the Logs tab

The Logs tab of a workflow run displays the **node run instance ID** alongside the workflow instance ID for each Script node execution. A copy button is rendered next to every instance ID. Use this to grab a node-run identifier and paste it into the Test modal's input selector to replay the exact past run.

***

### Subworkflow node

The Subworkflow node allows you to modularize complex workflows by invoking other workflows as reusable subcomponents. This approach simplifies process design, promotes reuse, and simplifies maintenance.

<Steps>
  <Step title="Add a Subworkflow Node">
    Select <strong>Start Subworkflow</strong> from the <strong>Select Next Node</strong> dropdown. Choose from workflows categorized as <strong>Local</strong> or <strong>Libraries</strong>.
  </Step>

  <Step title="Configure the Subworkflow Node">
    * <strong>Workflow Selection</strong>: Pick the workflow to invoke.
    * <strong>Open</strong>: Edit the subworkflow in a new tab.
    * <strong>Preview</strong>: View the workflow canvas in a popup.
    * <strong>Response Key</strong>: Set a key (e.g., <code>response\_key</code>) for output.
    * <strong>Input</strong>: Provide input in JSON format.
    * <strong>Output</strong>: Output is read-only JSON after execution.
  </Step>
</Steps>

<Tip>
  Use subworkflows for reusable logic such as data enrichment, validation, or external system calls.
</Tip>

#### Execution logic and error handling

* Parent workflow waits for subworkflow completion before proceeding.
* If the subworkflow fails, the parent workflow halts at this node.
* Subworkflow output is available to downstream nodes via the response key.
* Logs include workflow name, instance ID, and node statuses for both parent and subworkflow.

<Warning>
  If a subworkflow is deleted, an error displays: <code>\[name] subworkflow not found.</code>
</Warning>

<Check>
  Subworkflow runs are recorded in workflow instance history for traceability.
</Check>

#### Console logging, navigation, and read-only mode

* Console shows input/output, workflow name, and instance ID for each subworkflow run.
* Open subworkflow in a new tab for debugging from the console.
* Breadcrumbs enable navigation between parent and subworkflow details.
* In committed/upper environments, subworkflow configuration is read-only and node runs are disabled (preview/open only).

<Info>
  Subworkflow instances are logged in history, and you can navigate between parent and child workflow runs for comprehensive debugging.
</Info>

#### Use case: CRM Data Retrieval with subworkflows

Suppose you need to retrieve CRM details in a subworkflow and use the output for further actions in the parent workflow.

<Steps>
  <Step title="Create the Subworkflow">
    Design a workflow that connects to your CRM system, fetches user details, and outputs the data in a structured JSON format.
  </Step>

  <Step title="Add a Subworkflow Node in the Parent Workflow">
    In your main workflow, add a Subworkflow Node and select the CRM retrieval workflow. Map any required input parameters.
  </Step>

  <Step title="Use Subworkflow Output in Parent Workflow">
    Downstream nodes in the parent workflow can reference the subworkflow's output using the defined <code>responseKey</code>.

    ```json theme={"system"}
    {
      "crmData": "${responseKey}"
    }
    ```
  </Step>

  <Step title="Monitor and Debug">
    Use the console to view input/output data, workflow names, and instance IDs. Open subworkflow runs in new tabs for detailed debugging.
  </Step>
</Steps>

<Info>
  This modular approach allows you to build scalable, maintainable integrations by composing workflows from reusable building blocks.
</Info>

***

### End node

The End node signifies the termination of a workflow's execution. It collects the final output and completes the workflow process.

* Receives input in JSON format from the previous node.
* Output represents the final data model of the workflow.
* Multiple End nodes are allowed for different execution paths.

<Info>
  If the node's output doesn't meet mandatory requirements, it will be flagged as an error to ensure all necessary data is included.
</Info>

***

### Running and stopping workflows

You can run a workflow directly from the editor to test and debug it, and stop it while it is running.

* **Run Workflow**: Click **Run Workflow** in the workflow editor toolbar to start a new workflow instance. You can provide start data in JSON format before running.
* **Stop Run**: While a workflow instance is running, the button changes to **Stop Run**. Click it to cancel the instance. All in-progress and scheduled nodes are marked as cancelled.

Workflow instances can have the following statuses:

| Status        | Description                                            |
| ------------- | ------------------------------------------------------ |
| **Started**   | The workflow instance is currently running             |
| **Finished**  | The workflow instance completed successfully           |
| **Failed**    | The workflow instance encountered an error             |
| **Cancelled** | The workflow instance was manually stopped by the user |

***

## Integration with external systems

This example demonstrates how to integrate FlowX with an external system, in this example, using Airtable, to manage and update user credit status data. It walks through the setup of a data source, defining API endpoints, creating workflows, and linking them to BPMN processes in FlowX Designer.

<Check>
  Before going through this example of integration, we recommend:

  * Create your own base and table in Airtable. For more information, see the [Airtable base creation guide](https://www.airtable.com/guides/build/create-a-base).
  * Review the [Airtable Web API documentation](https://airtable.com/developers/web/api/introduction) to get familiarized with the Airtable API.
</Check>

### Integration in FlowX.AI

<Steps>
  <Step title="Define a Data Source">
    Navigate to the **Integration Designer** and create a new data source:

    * Name: **Airtable Credit Data**
    * **Base URL**: `https://api.airtable.com/v0/`

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/airtable1.png)
    </Frame>
  </Step>

  <Step title="Define Endpoints">
    In the **Endpoints** section, add the necessary API endpoints for system integration:

    1. **Get Records Endpoint**:
       * **Method**: GET
       * **Path**: `/${baseId}/${tableId}`
       * **Path Parameters**: Add the values for the baseId and for the tableId so they will be available in the path.
       * **Header Parameters**: Authorization Bearer token

    See the [API docs](https://airtable.com/developers/web/api/list-records).

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/airtable2.png)
    </Frame>

    2. **Create Records Endpoint**:
       * **Method**: POST
       * **Path**: `/${baseId}/${tableId}`
       * **Path Parameters**: Add the values for the baseId and for the tableId so they will be available in the path.
       * **Header Parameters**:
         * `Content-Type: application/json`
         * Authorization Bearer token
       * **Body**: JSON format containing the fields for the new record. Example:

    ```json theme={"system"}
       {
        "typecast": true,
        "records": [
            {
                "fields": {
                    "First Name": "${firstName}",
                    "Last Name": "${lastName}",
                    "Age": ${age},
                    "Gender": "${gender}",
                    "Email": "${email}",
                    "Phone": "${phone}",
                    "Address": "${address}",
                    "Occupation": "${occupation}",
                    "Monthly Income ($)": ${income},
                    "Credit Score": ${creditScore},
                    "Credit Status": "${creditStatus}"
                }
            }
        ]
    }
    ```

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/airtable3.png)
    </Frame>
  </Step>

  <Step title="Design the Workflow">
    1. **Open the Workflow Designer** and create a new workflow.
       * Provide a name and description.

    2. **Configure Workflow Nodes**:
       * **Start Node**: Initialize the workflow.

    <Check>
      On the start node add the data that you want to extract from the process. This way when you will add the **Start Workflow Integration** node action it will be populated with this data.

      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/start_data.gif)

      ```json theme={"system"}
      {
      "firstName": "${firstName}",
      "lastName": "${lastName}",
      "age": ${age},
      "gender": "${gender}",
      "email": "${email}",
      "phone": "${phone}",
      "address": "${address}",
      "occupation": "${occupation}",
      "income": ${income},
      "creditScore": ${creditScore},
      "creditStatus": "${creditStatus}"
      }
      ```

      Make sure these keys are also mapped in the data model of your process with their corresponding attributes.
    </Check>

    * **REST Node**: Set up API calls:
      * **GET Endpoint** for fetching records from Airtable.
      * **POST Endpoint** for creating new records.
    * **Condition Node**: Add logic to handle credit scores (e.g., triggering a warning if the credit score is below 300).

    <Tip>
      Condition example:

      ```json theme={"system"}
      input.responseKey.data.records[0].fields["Credit Score"] < 300
      ```
    </Tip>

    * **Script Node**: Include custom scripts if needed for processing data (not used in this example).
    * **End Node**: Define the end of the workflow with success or failure outcomes.

    <video />
  </Step>

  <Step title="Link the Workflow to a Process">
    1. **Integrate the workflow** into a BPMN process:
       * Open the process diagram and include a **User Task** and a **Receive Message Task**.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/bpmn_airtable.png)
    </Frame>

    <Info>
      In this example, we'll use a User Task because we need to capture user data and send it to our workflow.
    </Info>

    2. **Map Data** in the **UI Designer**:
       * Create the data model
       * Link data attributes from the data model to form fields, ensuring the user input aligns with the expected parameters.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/data_model_id.png)
    </Frame>

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/ut_dat_input.gif)
    </Frame>

    3. **Add a Start Integration Workflow** node action:

    * Make sure all the input will be captured.

    <video />
  </Step>

  <Step title="Monitor Workflow and Capture Output">
    **Receive Workflow Output**:

    * Use the **Receive Message Task** to capture workflow outputs like status or returned data.
    * Set up a **Data stream topic** to ensure workflow output is mapped to a predefined key.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/id_kafka_receive.png)
    </Frame>
  </Step>

  <Step title="Start the integration">
    * Start your process to initiate the workflow integration. It should add a new user with the details captured in the user task.

    <video />

    * Check if it worked by going to your base in Airtable. You can see, our user has been added.

    <video />
  </Step>
</Steps>

***

This example demonstrates how to integrate Airtable with FlowX to automate data management. You configured a data source, set up endpoints, designed a workflow, and linked it to a BPMN process.

***

## Export and import

You can export and import both **data sources** and **workflows** as ZIP files to transfer them between projects or environments (for example, from development to UAT to production).

### Exporting

To export a data source or workflow:

1. Navigate to the **Data Sources** or **Workflows** list in Integration Designer
2. Open the context menu for the resource you want to export
3. Select **Export**
4. The resource is downloaded as a ZIP file containing the full configuration

**What's included in the export:**

* **Data Sources** - data source configuration, endpoints, NoSQL operations, MCP tools
* **Workflows** - workflow nodes and their configurations

### Importing

To import a data source or workflow:

1. Navigate to the **Data Sources** or **Workflows** list in Integration Designer
2. Open the context menu and select **Import from ZIP**
3. Select the ZIP file exported from another project or environment
4. If resources with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting resource (or use **Apply to all**):
   * **Keep both** - imports the resource as a new copy alongside the existing one
   * **Replace** - overwrites the existing resource with the imported version
   * **Skip this one** - keeps the existing resource unchanged
6. Click **Continue** to complete the import

<Info>
  Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.
</Info>

## FAQs

<AccordionGroup>
  <Accordion title="Can I call GraphQL, SOAP, or gRPC endpoints?">
    **A:** For external API calls, the Integration Designer uses **REST (HTTP)** as the communication protocol. There is no dedicated GraphQL, SOAP, gRPC, or JDBC data source type — but protocols that run over HTTP can be called through a REST data source.

    You can call a **GraphQL** endpoint by using a REST data source configured with the **POST** method, sending the GraphQL query as a JSON body:

    ```json theme={"system"}
    {
      "query": "mutation { updatePerson(input: { name: \"${input.name}\" }) { id status } }"
    }
    ```

    Set the endpoint content type to `application/json` and map the response as you would for any REST call.

    You can call a **SOAP** web service the same way: configure a **POST** REST endpoint, set the **Content type** to **Raw**, put the SOAP envelope in the request body, and add the `Content-Type` (`text/xml` or `application/soap+xml`) and `SOAPAction` request headers. The XML response is parsed automatically, so you can map its fields like any JSON response — see [Receiving XML and SOAP responses](#receiving-xml-and-soap-responses). There is no WSDL import or automatic envelope/fault generation; you build the envelope yourself.

    **gRPC** and **JDBC** are not supported — they are not HTTP-based and have no data source type.

    The Integration Designer also supports specialized data source types beyond REST: FlowX Database, Unmanaged MongoDB, MCP Server, Knowledge Base, Email Trigger, Email Sender, Incoming Webhook, and Microsoft Outlook. See [Data sources](#data-sources) for details.
  </Accordion>

  <Accordion title="How is security handled in integrations??">
    **A:** The Integration Service handles all security aspects, including certificates and secret keys. Authorization methods like Service Token, Bearer Token, and OAuth 2.0 are supported.
  </Accordion>

  <Accordion title="How are errors handled?">
    **A**: Errors are logged within the workflow and can be reviewed in the monitoring dedicated console for troubleshooting and diagnostics
  </Accordion>

  <Accordion title="Can I import endpoint specifications in the Integration Designer?">
    **A**: You can import full data sources (including their endpoints) and workflows via ZIP files using the **Import from ZIP** option in the context menu. See the [Export and import](#export-and-import) section for details.

    Importing endpoint specifications from external formats like Swagger/OpenAPI is not yet supported. Endpoints must be defined manually within the data source configuration.
  </Accordion>

  <Accordion title="Can I cache responses from all endpoint methods?">
    **A**: No, caching is only available for GET endpoints. POST, PUT, PATCH, and DELETE methods cannot be cached as they are designed to modify data rather than retrieve it.
  </Accordion>

  <Accordion title="What happens if the cache service fails?">
    **A**: FlowX.AI automatically falls back to calling the external API directly. Your workflows always receive correct data even if caching fails. The failure is logged for monitoring purposes.
  </Accordion>

  <Accordion title="Can I use different cache policies for the same endpoint in different workflows?">
    **A**: No, the cache policy is configured at the endpoint level in the Data Source definition. All workflows using that endpoint share the same cache. If you need different caching behavior, create separate endpoint definitions.
  </Accordion>

  <Accordion title="How do I know if my workflow is using cached data?">
    **A**: Cache status is visible in both the endpoint testing modal and the workflow console logs. You'll see whether the response came from cache (hit) or from the external API (miss), along with the cache key and TTL information.
  </Accordion>
</AccordionGroup>

***

## Academy courses

<CardGroup>
  <Card title="Integration Designer course" icon="graduation-cap" href="https://academy.flowx.ai/explore/integration-designer">
    Hands-on course covering systems, data sources, workflows, and REST integration patterns
  </Card>

  <Card title="Data Mappers course" icon="graduation-cap" href="https://academy.flowx.ai/explore/5data-mappers">
    Learn Kafka data mapping and transformation between process and integration workflows
  </Card>
</CardGroup>

<Tip>
  **Academy playground projects** — if you're enrolled in the FlowX Academy, explore working examples:

  * [**integrationDesigner**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/d5221a29-1d95-4f7f-a38d-a3446013ce23/config/cf068a44-a551-4eb2-9e96-593726d7c50a/processes) — REST API integration workflow patterns
  * [**dataMappers**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/ee7acc40-9f7d-4b61-adf4-e391f013b33a/config/39c9ceda-e694-46a0-a985-76d4d7c4fcd3/processes) — data mapping between process and workflows
  * [**database**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/f69d3816-8746-43bc-ac89-121a28710ee5/config/4082e8f4-2f17-4071-84ea-a0692b34fc83/processes) — FlowX Database operations (find, insert, update)
  * [**file\_handling\_ID**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/e00957d9-f8cb-490b-9d6c-23f1c4537e88/config/60cd1ae2-b856-4583-8227-f728368f0d23/processes) — file upload and handling in integration workflows
</Tip>


# Overview
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/integrations-overview

Integrations connect legacy systems, third-party applications, and external data sources to the FlowX Engine through two complementary approaches.

FlowX.AI supports two integration approaches, each suited to different scenarios:

* **Integration Designer** — a visual, low-code environment for building integration workflows and connecting to data sources such as REST APIs, databases, MCP servers, and knowledge bases. Suitable for most integration scenarios without requiring custom code.
* **Custom integrations** — Kafka-based microservices (Connectors) you develop and deploy when working with legacy systems, RPAs, or custom file exchange solutions that require bespoke logic.

The sections below focus on custom (Kafka-based) integrations. For Integration Designer, see the [Integration Designer](./integration-designer) guide.

***

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/custom_intg.svg)

#### High-level architecture

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/intgr_final.png)

## Developing a custom integration

Developing custom integrations for the FlowX.AI platform is a straightforward process. You can use your preferred technology to write the necessary custom code, with the requirement that it can send and receive messages from the **Kafka** cluster.

#### Steps to create a custom integration

Follow these steps to create a custom integration:

1. Develop a microservice, referred to as a "Connector," using your preferred tech stack. The Connector should listen for Kafka events, process the received data, interact with legacy systems if required, and send the data back to Kafka.

2. Configure the [process definition](../../building-blocks/process/process-definition) by adding a [message](../../building-blocks/node/message-send-received-task-node) send action in one of the [nodes](../../building-blocks/node/node). This action sends the required data to the Connector.

3. Once the custom integration's response is ready, send it back to the FlowX.AI Engine. Keep in mind that the process will wait in a receive message node until the response is received.

For Java-based Connector microservices, you can use the following startup code as a quickstart guide:

<Card title="Quickstart connector" href="https://github.com/flowx-ai/quickstart-connector" icon="link" />

## Managing an integration

#### Managing Kafka topics

It's essential to configure the engine to consume events from topics that follow a predefined naming pattern. The naming pattern is defined using a topic prefix and suffix, such as "*ai.flowx.dev.engine.receive*."

<Tip>
  We recommend the following naming convention for your topics:

  ```yaml theme={"system"}
   topic:
      naming:
        package: "ai.flowx."
        environment: ""
        version: ".v1"
        prefix: ${kafka.topic.naming.package}${kafka.topic.naming.environment}
        suffix: ${kafka.topic.naming.version}
        engineReceivePattern: engine.receive

      pattern: ${kafka.topic.naming.prefix}${kafka.topic.naming.engineReceivePattern}*
  ```
</Tip>

## Integration types

FlowX.AI supports multiple integration approaches to connect with external systems and data sources:

### Integration Designer

The Integration Designer provides a visual interface for managing data sources and building integration workflows without extensive coding.

<CardGroup>
  <Card title="RESTful Systems" icon="globe">
    Connect to external REST APIs for data exchange and system integration
  </Card>

  <Card title="FlowX Database" icon="database">
    Store and retrieve data using the FlowX internal database
  </Card>

  <Card title="MCP Integration" icon="plug">
    Connect to Model Context Protocol servers to enable AI agents to use external tools
  </Card>

  <Card title="Knowledge Base" icon="brain">
    Create contextual knowledge repositories for AI agents to query
  </Card>

  <Card title="Email Trigger" icon="envelope-open-text">
    Start process instances automatically when emails arrive in a monitored mailbox
  </Card>

  <Card title="Email Sender" icon="paper-plane">
    Send emails and reply to received emails directly from process nodes via SMTP
  </Card>

  <Card title="Incoming Webhook" icon="webhook">
    Trigger processes from external HTTP POST requests with API key authentication
  </Card>

  <Card title="Microsoft Outlook" icon="envelope">
    Connect to Outlook via MS Graph API for reading and sending emails
  </Card>

  <Card title="File Storage" icon="folder-open">
    Move files in and out of external FTP, SFTP, S3, or Azure Blob storage
  </Card>
</CardGroup>

<Card title="Learn more about Integration Designer" href="./integration-designer" icon="link" />

### Custom integrations

For more complex scenarios or when working with legacy systems, you can develop custom integrations using Kafka messaging.

<Card title="Building a custom connector" href="./building-a-connector" icon="link" />


# Knowledge Base integration
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview

Learn how to create and manage FlowX Knowledge Bases to provide AI agents with contextual information from static documents and dynamic data feeds.

## Overview

The FlowX Knowledge Base integration enables you to ingest static documents into contextual Knowledge Bases that AI agents can query when preparing responses. This integration provides a centralized repository for information that can be semantically searched and retrieved by AI agents during workflow execution.

<Info>
  Knowledge Bases use vector embeddings and semantic search to find the most relevant information for AI agent queries.
</Info>

## Key features

* **Centralized content management**: Upload documents into organized Knowledge Bases
* **Multiple stores**: Manage content by splitting it across different stores for better organization
* **Semantic search**: AI agents can find relevant information using natural language queries
* **Multiple search modes**: Choose between hybrid, semantic, or keyword search algorithms
* **Testing capabilities**: Test queries and operations in isolation before adding them to workflows
* **Content versioning**: Append, replace, or delete stores with full traceability
* **Relevance scoring**: Understand which content chunks are most relevant for agent responses
* **Audit trail**: Track all store operations with user and timestamp information
* **Version tracking**: Knowledge Base entries are tied to app versions for consistency

## How it works

```mermaid theme={"system"}
graph LR
    A[Upload Documents] -->|Ingest| B[Knowledge Base]
    B -->|Chunk & Index| D[Vector Database]
    E[Custom Agent Node] -->|Query| D
    D -->|Return Chunks| E
    E -->|Generate Response| F[AI Service]
```

### High-level workflow

1. **Create Knowledge Base**: Add a new Knowledge Base data source in Integration Designer
2. **Ingest content**: Upload documents into stores
3. **Automatic chunking**: Content is automatically split into chunks and indexed for semantic search
4. **Query in workflows**: AI agents query the Knowledge Base to find relevant information
5. **Monitor usage**: Track which chunks are used and their relevance scores in console logs

## Main capabilities

### Content ingestion

<CardGroup>
  <Card title="Manual upload" icon="upload">
    Upload PDF documents directly from the Knowledge Base admin interface
  </Card>
</CardGroup>

### Content management

<Steps>
  <Step title="Organize by stores">
    Manage content by organizing it into separate stores for better control and traceability
  </Step>

  <Step title="Append or replace">
    Update existing stores by appending new information or replacing it entirely
  </Step>

  <Step title="Delete when needed">
    Remove stores and all associated chunks when they're no longer needed
  </Step>
</Steps>

### AI agent integration

AI agents can use Knowledge Bases with the ReAct (Reasoning and Acting) model to:

* Find relevant information based on user queries
* Understand which stores provided the information
* See relevance scores for retrieved chunks
* Make informed decisions based on contextual knowledge

## Stores

Stores represent individual collections of information within a Knowledge Base. Each store can be:

* **Manual**: Files uploaded through the Knowledge Base admin interface
* **Workflow**: Content ingestion through workflow operations. The Update Knowledge Base node accepts a file path, so workflows can ingest content uploaded earlier in the run (5.8.0+)

<Frame>
  ![Knowledge Base Stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_stores.png)
</Frame>

### Store lifecycle

```mermaid theme={"system"}
stateDiagram-v2
    [*] --> New: Create
    New --> Processing: Upload/Ingest
    Processing --> Ready: Complete
    Processing --> Failed: Error
    Ready --> Processing: Update
    Ready --> Failed: Partial failure
    Ready --> MarkedForRemoval: Delete
    Failed --> Processing: Retry
    MarkedForRemoval --> [*]
```

Stores progress through the following states:

| State          | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| **New**        | Store created, awaiting content                                   |
| **Processing** | Content is being uploaded, chunked, and indexed                   |
| **Ready**      | Content is fully processed and available for queries              |
| **Failed**     | Processing encountered an error, or content is partially degraded |
| **Deleting**   | Store is scheduled for deletion                                   |

### Audit trail

All store operations are tracked in the audit trail with full traceability:

| Field              | Description                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| **Operation type** | `ADD_CONTENT_SOURCE`, `REPLACE_CONTENT_SOURCE`, `DELETE_CONTENT_SOURCE`, `ADD_CONTENT`, `REMOVE_CONTENT` |
| **Triggered by**   | How the operation was initiated: Manual, API, Workflow, or Test                                          |
| **User**           | The user who performed the operation (for manual operations)                                             |
| **Status**         | Final operation state: Completed or Failed                                                               |
| **Timestamp**      | When the operation occurred                                                                              |

<Tip>
  Use the audit trail to track who made changes to Knowledge Base content and when, which is useful for compliance and troubleshooting.
</Tip>

## Search modes

Knowledge Bases support three search algorithms that determine how queries are matched against stored content:

| Search Mode  | Description                                                                     | Best For                                                          |
| ------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Hybrid**   | Combines semantic and keyword search for balanced results                       | General-purpose queries where both meaning and exact terms matter |
| **Semantic** | Uses vector embeddings to match by meaning, not exact words                     | Natural language questions, conceptual queries                    |
| **Keyword**  | Term-based matching that also finds closely related words, not just exact terms | Precise lookups, technical terms, codes, identifiers              |

<Tip>
  Start with **Hybrid** search mode for most use cases. Switch to Semantic for conversational queries or Keyword for exact term lookups.
</Tip>

***

## Chunks and search

Chunks are small snippets of content that are indexed in the vector database for semantic search. When an AI agent queries a Knowledge Base, the most relevant chunks are returned based on:

* **Content similarity**: Semantic meaning of the query vs. chunk content
* **Relevance score**: Percentage indicating how relevant the chunk is (0-100%)
* **Metadata filters**: Optional filters built from typed operators and AND/OR logic — see [Filtering by metadata](./managing-content#filtering-by-metadata)

<Tip>
  You can test different query parameters to see which chunks are returned and their relevance scores before using the Knowledge Base in production workflows.
</Tip>

## Use cases

### Product documentation assistant

Create a Knowledge Base with product documentation and allow AI agents to answer customer questions based on the latest documentation.

### Policy compliance

Upload company policies and compliance documents. AI agents can reference these when processing requests to ensure compliance.

### Dynamic knowledge updates

Upload updated documents to Knowledge Bases to keep AI agent knowledge current. Content can be managed manually through the admin interface or programmatically through workflows and APIs.

### Multi-source information synthesis

Organize information across multiple stores and let AI agents synthesize information from different sources to provide comprehensive answers.

## Limitations

<Warning>
  **Current limitations:**

  * AI agents can only use one Knowledge Base per Custom Agent node
  * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
  * Store renaming is not available
</Warning>

***

## Creating a knowledge base

### Prerequisites

Before you begin, ensure you have:

* Access to FlowX Designer with appropriate permissions
* A project where you want to add the Knowledge Base
* Content ready to ingest (PDF documents or JSON data)

### Setup steps

To add a new Knowledge Base data source:

<Steps>
  <Step title="Navigate to Integration Designer">
    Go to **FlowX Designer** → **Workspaces** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources**
  </Step>

  <Step title="Create new data source">
    Click **Add New Data Source** and select **FlowX Knowledge Base** as the data source type
  </Step>

  <Step title="Configure basic settings">
    Fill in the required fields with the following information
  </Step>
</Steps>

<Frame>
  ![Add Knowledge Base](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/add_kb.png)
</Frame>

### Configuration fields

#### Name

The unique identifier for your Knowledge Base within the project.

<ParamField type="string">
  **Validation rules:**

  * **Required**: Field cannot be empty
  * **Uniqueness**: Must be unique within the project
  * **Special characters**: Only letters, numbers, and the following characters are allowed: `[]`, `()`, `.`, `_`, `-`
  * **Length**: Minimum 3 characters, maximum 50 characters
</ParamField>

#### Description

An optional description explaining the purpose and contents of the Knowledge Base.

<ParamField type="string">
  Provide additional context about what information this Knowledge Base contains and how it should be used.
</ParamField>

### Example configuration

Here's an example of a well-configured Knowledge Base:

```yaml theme={"system"}
Name: Product Documentation KB
Description: Contains all product documentation, user guides, and FAQ documents for the customer support AI agent
```

### After creation

Once you've created a Knowledge Base, you'll see three tabs:

<CardGroup>
  <Card title="Stores" icon="folder">
    View and manage all stores ingested into the Knowledge Base
  </Card>

  <Card title="Chunks" icon="cube">
    Search and view the individual chunks created from your content
  </Card>

  <Card title="Metadata" icon="tags">
    Define custom metadata keys used to filter and scope retrieval
  </Card>
</CardGroup>

<Frame>
  ![Knowledge Base Dashboard](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kb_dashboard.png)
</Frame>

***

## Next steps

<CardGroup>
  <Card title="Managing Content" href="./managing-content" icon="folder">
    Upload documents and manage stores
  </Card>

  <Card title="Using in Workflows" href="./using-knowledge-base-in-workflows" icon="workflow">
    Query Knowledge Bases from workflows
  </Card>

  <Card title="Testing Operations" href="./testing-knowledge-base" icon="flask">
    Test queries and operations before production use
  </Card>
</CardGroup>

## Related resources

<Card title="Integration Designer" href="../../integration-designer/designer-overview" icon="link">
  Integration Designer and data sources
</Card>

<Card title="Custom Agent Nodes" href="../../ai-agents/custom-agent-node" icon="link">
  Using AI agents in workflows
</Card>

<Card title="Integrations Overview" href="../../integrations-overview" icon="link">
  Integration ecosystem overview
</Card>


# Managing stores
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content

Learn how to upload documents, manage stores, and work with chunks in FlowX Knowledge Bases.

## Overview

Stores are the building blocks of a Knowledge Base. Each store represents a collection of related information that has been ingested, processed, and indexed for semantic search.

## Store types

There are two types of stores:

<CardGroup>
  <Card title="Manual" icon="upload">
    Files uploaded directly through the Knowledge Base admin interface
  </Card>

  <Card title="Workflow" icon="diagram-project">
    JSON content ingestion through workflows (planned for future release)
  </Card>
</CardGroup>

## Viewing stores

Navigate to your Knowledge Base to see all stores. The **Stores** tab displays:

<Frame>
  ![Stores List](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_stores.png)
</Frame>

### Store information

Each row shows:

<ResponseField name="Type" type="string">
  * **Manual**: Files uploaded in the Knowledge Base page
  * **Workflow**: Content ingestion through workflow variables (planned for future release)
</ResponseField>

<ResponseField name="Store" type="string">
  The unique name of the store within the Knowledge Base
</ResponseField>

<ResponseField name="Status" type="string">
  Current processing state:

  * **New**: Store created, awaiting content upload
  * **Processing**: Content is being uploaded, chunked, and indexed
  * **Ready**: Content is fully processed and available for queries
  * **Failed**: An error occurred during processing, or content is partially degraded

  Status badges update in real-time — you don't need to refresh the page to see status changes.
</ResponseField>

<ResponseField name="Updated by" type="string">
  * **Username**: For files uploaded in the Knowledge Base page
  * **Workflow name**: For content ingested through workflows (planned for future release)
</ResponseField>

<ResponseField name="Updated at" type="timestamp">
  Timestamp of the last upload or workflow operation execution
</ResponseField>

## Uploading documents

<Steps>
  <Step title="Navigate to Knowledge Base">
    Open your Knowledge Base in FlowX Designer and select the **Stores** tab.
  </Step>

  <Step title="Open the upload dialog">
    Click the **+** button in the top-right of the Stores tab. A file picker opens.
  </Step>

  <Step title="Select file">
    Choose a PDF file from your computer and click **Open**. The **Upload Store** modal appears.
  </Step>

  <Step title="Set the store name">
    The **Name** field is pre-filled with the file name (without extension). Edit it if needed — the name must be unique within the Knowledge Base.
  </Step>

  <Step title="Review metadata (optional)">
    The **Metadata** section shows the metadata schema defined for this Knowledge Base. If no metadata is defined, a "No metadata defined" placeholder appears — click **Go to Metadata Setup** to configure a schema on the **Metadata** tab before uploading. See [User-defined metadata](#user-defined-metadata) for details.
  </Step>

  <Step title="Upload">
    Click **Upload** to start the ingestion process. The store appears in the list with status **Processing**, and transitions to **Ready** once chunking and indexing complete.
  </Step>
</Steps>

<Frame>
  ![Upload Store modal with Name field and Metadata section](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/upload-store.png)
</Frame>

### File requirements

<Warning>
  **Supported formats (current release):**

  * PDF files only

  **File size:**

  * Maximum file size: 20 MB (can be changed using environment variables)

  **Future releases will support:**

  * Images
  * PowerPoint presentations
  * Word documents
  * Excel spreadsheets
</Warning>

### Store naming

When uploading a document, you must provide a unique store name:

<Tip>
  **Store name rules:**

  * Must be unique within the Knowledge Base
  * Default name is the file name without extension
  * Choose descriptive names for easy identification
  * Consider using versioning in names (e.g., "Product Guide v2.1")
</Tip>

### Duplicate stores

If you select a file with the same name as an existing store, you'll see a warning:

```
A Store with this name already exists. We recommend updating the existing store instead.
```

**Available options:**

* **Append Content**: Add the new document's content to the existing store
* **Replace Content**: Replace the existing content with the new document
* **Cancel**: Choose a different name or file

## Managing stores

Once content is uploaded and processed, you can perform the following operations:

<Frame>
  ![Manage Stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/content_ops.png)
</Frame>

### Append content

Add new content to an existing store without removing the existing chunks.

<Steps>
  <Step title="Select store">
    Click on the store you want to update
  </Step>

  <Step title="Choose Append Content">
    Select the **Append Content** operation
  </Step>

  <Step title="Upload new file">
    Select a new PDF file with additional content
  </Step>

  <Step title="Confirm">
    The new content will be processed and added to the existing chunks
  </Step>
</Steps>

**Use case:** Adding a new chapter to existing documentation or supplementing information without losing the original content.

### Replace content

Replace all existing content in a store with new content.

<Steps>
  <Step title="Select store">
    Click on the store you want to replace
  </Step>

  <Step title="Choose Replace Content">
    Select the **Replace Content** operation
  </Step>

  <Step title="Upload new file">
    Select a new PDF file that will replace the existing content
  </Step>

  <Step title="Confirm">
    All existing chunks will be deleted and new chunks will be created from the new content
  </Step>
</Steps>

<Warning>
  **Replace Content** will permanently delete all existing chunks from the store. This operation cannot be undone.
</Warning>

**Use case:** Updating documentation to a new version where the old content is no longer relevant.

### Delete store

Remove a store and all its associated chunks from the Knowledge Base.

<Steps>
  <Step title="Select store">
    Click on the store you want to delete
  </Step>

  <Step title="Choose Delete">
    Select the **Delete Store** operation
  </Step>

  <Step title="Confirm deletion">
    Confirm that you want to permanently delete the store
  </Step>
</Steps>

<Warning>
  Deleting a store will:

  * Remove all chunks generated from that content
  * Permanently delete the content from the Knowledge Base
  * This operation cannot be undone
</Warning>

## Store states

Stores progress through different states during their lifecycle. Status badges update in real-time — you don't need to refresh the page to see transitions.

### New

The initial state after content is uploaded to the Knowledge Base.

**What's happening:**

* File has been transferred to the FlowX platform
* Content is being validated and queued for processing

**Duration:** Usually a few seconds, depending on file size

### Processing

Content is being chunked, embedded, and indexed in the vector database.

**What's happening:**

* Content is being extracted from the document
* Text is being split into semantically meaningful chunks
* Chunks are being embedded and indexed in the vector database

**Duration:** Can take from seconds to minutes depending on content size

### Ready

Store is fully processed and available for queries.

**What you can do:**

* Query the store in AI agents
* View individual chunks
* Append or replace content
* Delete the store

### Failed

An error occurred during processing, or the store is partially degraded.

**What to do:**

1. Check the error message in the Store History modal
2. Verify the file format and content
3. Retry the operation

<Frame>
  ![Failed State](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/console_history.png)
</Frame>

## Error handling

When processing fails, the store will show a warning indicator.

### Error states and recovery

<Accordion title="Upload failed">
  **Cause:** File upload was interrupted or the file format is invalid

  **Solution:**

  * Verify the file format (must be PDF)
  * Check your network connection
  * Try uploading again
</Accordion>

<Accordion title="Chunking failed">
  **Cause:** Error occurred while processing the content

  **Solution:**

  * Check the Store History for specific error details
  * Verify the file is not corrupted
  * Contact support if the issue persists
</Accordion>

<Accordion title="Retry behavior">
  When retrying a failed operation:

  * Any chunks already created will be deleted
  * The content will be processed entirely from the beginning
  * No duplicate chunks will be created
</Accordion>

### Warning indicators

When a store has a failed update:

* **Yellow warning icon** appears on the store row
* **Tooltip message**: "Last Store update failed. Check history."
* **Dismiss trigger**: The warning is automatically dismissed after a successful update

## Viewing store history

<Info>
  Store History is a low-priority feature that may be available in future releases.
</Info>

Store History will show all operations performed on a store:

| Operation       | Description                                      |
| --------------- | ------------------------------------------------ |
| Upload Document | Creates store and inserts content                |
| Append Content  | Adds new content to existing chunks              |
| Replace Content | Deletes existing content and inserts new content |
| Delete Store    | Removes the store and all chunks                 |

Each history entry will include:

* Timestamp
* User or workflow name
* Operation type (Manual/Workflow/Test)
* Operation performed
* View option (for uploaded files or JSON payloads)

## Working with chunks

Chunks are the individual pieces of content that AI agents query. To view and test chunks:

<Steps>
  <Step title="Navigate to Chunks tab">
    Click the **Chunks** tab in your Knowledge Base
  </Step>

  <Step title="Search chunks">
    Enter a query to search for relevant chunks
  </Step>

  <Step title="Filter results">
    Apply filters to refine the search results
  </Step>

  <Step title="Review chunks">
    Examine the returned chunks, their relevance scores, and metadata
  </Step>
</Steps>

<Frame>
  ![Chunks](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_chunks.png)
</Frame>

### Chunk information

Each chunk displays:

<ResponseField name="Relevance Score" type="percentage">
  How relevant the chunk is to your query (0-100%)
</ResponseField>

<ResponseField name="Store" type="string">
  The store that generated this chunk (clickable link)
</ResponseField>

<ResponseField name="Submitted Content" type="link">
  Link to the original document or JSON payload that created this chunk
</ResponseField>

<ResponseField name="Chunk Content" type="text">
  The actual text content of the chunk
</ResponseField>

<ResponseField name="Chunk Metadata" type="object">
  System metadata associated with the chunk:

  * `source`: manual\_upload or from\_workflow
  * `path`: Document filepath or JSON payload
  * `chunk_id`: UUID from the vector database
  * `knowledge_base`: Knowledge Base ID

  User-defined metadata keys (if configured) are also included.
</ResponseField>

### User-defined metadata

You can define custom metadata keys on a Knowledge Base and assign values to stores. User-defined metadata enables filtering and scoping when searching chunks — for example, filtering by department, document version, or region.

#### Defining metadata keys

Metadata keys are managed on the **Metadata** tab of the Knowledge Base data source.

<Frame>
  ![Metadata tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_metadata.png)
</Frame>

To add a key, click **Add Metadata Key** and fill in the following fields:

| Field           | Description                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| **Name**        | Unique key name. Cannot be changed after creation.                                                   |
| **Type**        | Data type: `String`, `Number`, `Boolean`, `Enum`, or `Date`. Cannot be changed after creation.       |
| **Enum values** | Allowed values (only visible when **Type** is `Enum`). Values defined at creation cannot be removed. |
| **Description** | Optional free-text description of the key's purpose.                                                 |

<Tip>
  Name and type are locked after a key is saved. Only description and enum values (additions only) can be updated later.
</Tip>

#### Assigning metadata values

When uploading or appending a store (manually or through the **Update Knowledge Base** workflow node), a **Metadata** section appears in the upload modal listing all defined keys for the Knowledge Base. Assign a value to each relevant key before uploading. The values are stored alongside the content and propagated to the vector database.

#### Filtering by metadata

When searching chunks (in the **Chunks** tab or through the Context Retrieval workflow node), you can add metadata filters using the query builder. System metadata keys are always available as filter options alongside any user-defined keys.

<Info>
  The metadata filter UI is a full query builder with typed operators, AND/OR logic, and grouping.
</Info>

##### System metadata keys

System metadata keys are reserved names populated automatically by the platform. They are listed in the filter picker with human-readable labels and can be combined with user-defined keys.

| Key              | Type   | Scope | Description                                                                                            |
| ---------------- | ------ | ----- | ------------------------------------------------------------------------------------------------------ |
| `source`         | Enum   | Entry | How the entry was added: `manual_upload`, `from_workflow`, `test_operation`                            |
| `uploaded`       | Date   | Entry | TODO: description                                                                                      |
| `docName`        | String | Entry | TODO: description                                                                                      |
| `docType`        | Enum   | Entry | TODO: description (starter values include `pdf`, `xlsx`, `docx`, `txt`)                                |
| `docPages`       | Number | Entry | TODO: description                                                                                      |
| `storeOrigin`    | String | Entry | TODO: description                                                                                      |
| `chunkCounter`   | Number | Chunk | TODO: description                                                                                      |
| `chunkType`      | Enum   | Chunk | TODO: description (starter values include `table`, `header`, `section_header`, `picture`, `paragraph`) |
| `chunkSection`   | String | Chunk | TODO: description                                                                                      |
| `chunkPageStart` | Number | Chunk | TODO: description                                                                                      |
| `chunkEntry`     | String | Chunk | TODO: description                                                                                      |

<Note>
  If a user-defined metadata key collides with a reserved system name, it is automatically renamed to `<name>_user` on upgrade. Wire-level identifiers stay plain; the filter picker shows human labels (for example, `Doc type` for `docType`).
</Note>

Filters are expressed as conditions made of **field / operator / value**. Each condition uses operators appropriate to the metadata key's type:

| Type        | Available operators                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| **String**  | equals, not equals, contains, starts with, ends with, matches regex, in, not in, exists, is null           |
| **Number**  | equals, not equals, greater than, greater or equal, less than, less or equal, between, in, exists, is null |
| **Boolean** | is true, is false, exists                                                                                  |
| **Date**    | equals, before, after, between, exists, is null                                                            |
| **Enum**    | equals, not equals, in, not in, exists                                                                     |

Conditions are organized in **groups**. Within a group, conditions can be combined with `and` or `or`. Groups themselves are also combined with `and` or `or`, which lets you express non-trivial logic such as `(region = "EU" AND tier IN ["gold", "platinum"]) OR priority >= 5`.

Use **New Filter** to add a condition and **New Group** to add a nested group.

### Searching chunks

Use the **Chunks** tab to test how chunks will be retrieved by AI agents:

<ParamField type="string">
  Filter by a specific store. Default: all stores
</ParamField>

<ParamField type="string">
  Enter a natural language question or search query
</ParamField>

<ParamField type="select">
  Strategy used for retrieving context:

  * **Hybrid** (default) — combines semantic and keyword search
  * **Semantic** — vector similarity only
  * **Keywords** — lexical match only (hides **Min. Relevance Score**)
</ParamField>

<ParamField type="number">
  Maximum number of chunks to return. Range: 1-10. Default: 4.
</ParamField>

<ParamField type="percentage">
  Only return chunks with relevance score above this threshold. Range: 0-100%. Hidden when **Search Type** is **Keywords**.
</ParamField>

<ParamField type="boolean">
  Reorders results to surface the best matches. Improves quality but takes slightly longer.
</ParamField>

<ParamField type="object">
  Refine results using the query builder (see [Filtering by metadata](#filtering-by-metadata))
</ParamField>

<Tip>
  Use chunk search to understand what information AI agents will receive for different queries. This helps you optimize your Knowledge Base content and structure.
</Tip>

## Best practices

### Content organization

<Tip>
  **Organize by topic or version:**

  * Create separate stores for different topics
  * Use versioning in store names (e.g., "User Guide v1.0", "User Guide v2.0")
  * Group related documents in the same store using Append Content
</Tip>

### Content updates

<Tip>
  **Choose the right operation:**

  * Use **Append Content** when adding supplementary information
  * Use **Replace Content** when updating to a new version
  * Test queries after updates to verify the changes work as expected
</Tip>

### Error prevention

<Tip>
  **Avoid common errors:**

  * Ensure PDF files are not corrupted before uploading
  * Use unique, descriptive names for stores
  * Monitor the status of stores during processing
  * Check Store History when errors occur
</Tip>

## Next steps

<Card title="Using in Workflows" href="./using-knowledge-base-in-workflows" icon="diagram-project">
  Learn how to query Knowledge Bases from workflows
</Card>

## Related resources

<Card title="Knowledge Base Overview" href="./knowledge-base-overview" icon="link">
  Understanding Knowledge Base capabilities
</Card>


# Testing a knowledge base
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/testing-knowledge-base

Test create, append, replace, delete, edit-metadata, and query operations against a knowledge base on a deployed build before running them in production.

<Info>
  The **Test Knowledge Base** modal lets you exercise content-management operations against a knowledge base on a deployed build, without modifying a workflow first. Use it to validate a knowledge base after deploy, to load initial content, or to investigate retrieval issues from a production knowledge base.
</Info>

## Overview

Knowledge bases are populated and queried through workflows. The Test Knowledge Base modal gives you a direct, build-level UI for the same operations, so you can:

* Seed a newly created knowledge base with content immediately after deploy
* Append or replace store content without triggering a workflow run
* Spot-check what a query returns against the current knowledge base state
* Edit metadata on individual entries when a real-world correction is needed

All write actions performed from this modal are tagged with `source: manual` on the affected entries, so they remain distinguishable from workflow-driven changes.

## Opening the modal

<Steps>
  <Step title="Open a deployed build">
    Navigate to a project that has a knowledge base configured, and open the build where you want to test.
  </Step>

  <Step title="Click the play button">
    On the build, click the **play** button and select **Test Knowledge Base**.
  </Step>

  <Step title="Choose the knowledge base">
    In the modal header, open the knowledge base dropdown and select the knowledge base you want to act on. The dropdown lists both project knowledge bases and any knowledge bases referenced from libraries used by the build.
  </Step>
</Steps>

## Available actions

Six actions are available inside the modal. Each one is run by clicking **Test** after filling in the required fields.

### Create new store

Creates a new store in the selected knowledge base and ingests an initial document.

| Field          | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| **Store name** | Required. Must be unique within the knowledge base.                               |
| **Upload**     | Opens the file picker, filtered to PDF.                                           |
| **Metadata**   | Same metadata inputs available when uploading from the knowledge base admin view. |

If a store with the same name already exists, the modal shows the toast error "Store name already exists." and highlights the store-name input.

### Append to a store

Adds new content to an existing store, leaving prior chunks in place.

| Field          | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| **Store name** | Required. Searchable dropdown of existing stores.                                    |
| **Type**       | Either **From document** (PDF upload) or **From payload** (JSON in the code editor). |
| **Metadata**   | Metadata values applied to the appended content.                                     |

### Replace store content

Removes the existing content of a store and replaces it with new content.

| Field          | Description                                             |
| -------------- | ------------------------------------------------------- |
| **Store name** | Required. Searchable dropdown of existing stores.       |
| **Type**       | Either **From document** or **From payload**.           |
| **Metadata**   | New metadata values applied to the replacement content. |

<Warning>
  Replace is destructive. All existing chunks in the store are removed before the new content is added.
</Warning>

### Delete a store

Removes a store from the knowledge base.

| Field          | Description                                       |
| -------------- | ------------------------------------------------- |
| **Store name** | Required. Searchable dropdown of existing stores. |

### Edit metadata values

Updates metadata values on individual entries inside a store.

<Steps>
  <Step title="Select a store">
    Pick a store from the searchable dropdown. The entries of that store appear on the right side of the modal.
  </Step>

  <Step title="Select an entry">
    Click the entry you want to edit. Each entry card shows both user-defined and system metadata.
  </Step>

  <Step title="Edit metadata values">
    Use the metadata area on the left to update values. Metadata is grouped into two categories: **configured** (keys that already have a value) and **empty** (keys that have no value yet). When you populate an empty key and save, it moves to the configured category. The empty category is hidden when no keys remain in it.
  </Step>

  <Step title="Save or discard">
    Save commits the changes to the selected entry. Discard clears the selection and any unsaved edits. If you try to switch entries with unsaved changes, the modal prompts you to confirm.
  </Step>
</Steps>

<Note>
  Metadata **values** are editable, metadata **keys** are not. Adding, removing, or renaming a metadata key from the modal is intentionally not allowed because metadata filters elsewhere in the platform depend on the key set.
</Note>

### Query

Runs a retrieval against the knowledge base and shows which chunks come back.

| Field                | Description                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Query**            | Free-text query string.                                                                                                            |
| **Metadata filters** | Advanced query builder over all metadata keys, including system metadata. Store-level filtering is expressed as a metadata filter. |

Use this to validate retrieval quality, debug an AI agent that is pulling unexpected chunks, or confirm that a recent ingestion is searchable.

## Reading the results

When you click **Test**, the modal header shows progress and an action-specific summary on completion.

| Action                | Status header on completion               |
| --------------------- | ----------------------------------------- |
| Create new store      | `Created: [X] chunks`                     |
| Append to a store     | `Appended: [X] chunks`                    |
| Replace store content | `Deleted: [X] chunks   Added: [Y] chunks` |
| Delete a store        | `Deleted: [X] chunks`                     |
| Query                 | (no count, retrieved chunks listed below) |

The chunks pane below the header reflects the action:

* **Create / Append** — new chunks are listed with a badge. For Append, new chunks appear at the top of the list, above pre-existing ones.
* **Replace** — only the new chunks are shown, each with a badge.
* **Delete** — the chunks area is empty.
* **Query** — retrieved chunks are listed without a badge.

<Info>
  Only the first **10 chunks** are shown in the preview. A disclaimer is rendered above the chunks list when the result set is truncated.
</Info>

## Limitations

<Warning>
  * The preview shows at most 10 chunks per action.
  * Metadata keys cannot be added, removed, or edited from the modal — only values.
  * File uploads accept PDF only.
  * Edits made from this modal are tagged `source: manual` and remain distinguishable from workflow-driven changes.
</Warning>

## Related resources

<CardGroup>
  <Card title="Knowledge base overview" href="./knowledge-base-overview" icon="book-open">
    Concepts, stores, chunks, and search modes.
  </Card>

  <Card title="Managing stores" href="./managing-content" icon="folder">
    Design-time UI for store management.
  </Card>

  <Card title="Using a knowledge base in workflows" href="./using-knowledge-base-in-workflows" icon="diagram-project">
    Query, append, and replace from inside a workflow.
  </Card>

  <Card title="Custom agent nodes" href="../../ai-agents/custom-agent-node" icon="robot">
    Wire a knowledge base into an AI agent.
  </Card>
</CardGroup>


# Using Knowledge Base in workflows
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows

Learn how to query Knowledge Bases using Custom Agent and Context Retrieval nodes in workflows.

## Overview

Knowledge Bases can be integrated into workflows to enable AI agents and Context Retrieval nodes to query them for contextual information when generating responses.

<Warning>
  **Not available in v5.4**: Workflow-based content ingestion (adding, updating, or deleting Knowledge Base content from workflows) is planned for a future release. Currently, you can only upload content manually through the Knowledge Base interface.
</Warning>

## Choosing the right approach

There are two ways to query Knowledge Bases in workflows:

| Approach                 | Node                                                                        | When to use                                                                                                        |
| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Integrated RAG**       | [Custom Agent](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) | You want the AI to retrieve chunks and generate a response in a single step                                        |
| **Standalone retrieval** | [Context Retrieval](/5.9/ai-platform/agent-builder/context-retrieval)       | You want raw chunks returned without LLM processing, so you can filter, transform, or route them before generation |

***

## Using knowledge bases in custom agent nodes

Custom Agent nodes can query Knowledge Bases to retrieve contextual information when generating responses.

### Configuring custom agent with knowledge base

<Steps>
  <Step title="Add Custom Agent node">
    Add a Custom Agent node to your workflow
  </Step>

  <Step title="Configure the agent">
    Set up the basic agent configuration (operation prompt, etc.)
  </Step>

  <Step title="Enable Knowledge Base">
    In the **Knowledge Base** section, enable the Knowledge Base feature
  </Step>

  <Step title="Select Knowledge Base">
    Choose a Knowledge Base from the available options
  </Step>

  <Step title="Configure query parameters">
    Set the query parameters for retrieving chunks
  </Step>
</Steps>

<Frame>
  ![Custom Agent with KB](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kb_can.png)
</Frame>

### Knowledge base query configuration

<ParamField type="select">
  Select the Knowledge Base that the agent should query
</ParamField>

<ParamField type="number">
  Maximum number of chunks to retrieve (1-10). Default: 5
</ParamField>

<ParamField type="percentage">
  Minimum relevance score threshold (0-100%). Only chunks above this score will be included. Default: 70%
</ParamField>

<ParamField type="object">
  Refine retrieved chunks using the query builder. Click the **Metadata Filters** button to open a modal where you can compose structured filter conditions.

  Each condition is a **field / operator / value** triple. Operators vary by metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with **AND** or **OR**.

  To restrict results to a specific store, add a condition on the system metadata key `source`.

  The button label shows how many filters are currently active (e.g., "3 Filters Applied" or "No Filters Applied").

  <Info>
    The Metadata Filters modal supports typed operators, AND/OR logic, and grouping. See [Filtering by metadata](./managing-content#filtering-by-metadata) for the full operator list.
  </Info>
</ParamField>

<ParamField type="boolean">
  Toggle **ON** to enable advanced metadata filter expressions for more complex filtering logic. When turned on, you can write expression-based filters instead of using the structured filter UI.

  **Default:** `false`
</ParamField>

***

## Using knowledge bases in context retrieval nodes

Context Retrieval nodes retrieve relevant data from Knowledge Bases or conversation memory using semantic, keyword, or hybrid search. Unlike Custom Agent nodes, Context Retrieval nodes are dedicated to chunk retrieval without agent reasoning -- they are available under **Data Operations** in the workflow node palette.

### Configuring context retrieval with knowledge base

<Steps>
  <Step title="Add Context Retrieval node">
    Add a **Context Retrieval** node from the **Data Operations** category in the workflow editor
  </Step>

  <Step title="Select a source">
    Choose between **Knowledge Base** or **Memory** (Memory is only available in conversational workflows)
  </Step>

  <Step title="Select Knowledge Base">
    If using Knowledge Base as the source, select a Knowledge Base from the available options
  </Step>

  <Step title="Define the user query">
    Enter the search query, typically a process variable expression (e.g., `${userMessage}`)
  </Step>

  <Step title="Configure settings">
    Expand **Settings** to configure search type, max chunks, min relevance, metadata filters, and re-ranking
  </Step>
</Steps>

### Context retrieval configuration

<ParamField type="select">
  The data source to retrieve context from.

  **Options:**

  * **Knowledge Base** — search a connected Knowledge Base
  * **Memory** — search conversation memory (conversational workflows only)
</ParamField>

<ParamField type="select">
  Select the Knowledge Base to query. Only visible when **Source** is set to **Knowledge Base**.
</ParamField>

<ParamField type="string">
  The search query used to retrieve relevant chunks. Supports process variable expressions.

  **Example:** `${userMessage}`
</ParamField>

<ParamField type="select">
  The strategy used for retrieving context.

  **Options:**

  * **Hybrid** (default) — combines semantic and keyword search
  * **Semantic** — vector-based similarity search
  * **Keywords** — traditional keyword matching
</ParamField>

<ParamField type="number">
  How many relevant chunks to return (1-10).

  **Default:** `5`
</ParamField>

<ParamField type="percentage">
  The threshold a chunk must meet to be included in results (0-100%). Only visible when search type is **Hybrid** or **Semantic**.

  **Default:** `70%`
</ParamField>

<ParamField type="object">
  Refine results by filtering chunks based on their metadata properties. Click the button to open the query builder modal where you can compose structured filter conditions.

  Each condition is a **field / operator / value** triple. Operators vary by metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with **AND** or **OR**.

  The button label shows how many filters are currently active.

  <Info>
    Typed operators, AND/OR logic, and grouping are supported. See [Filtering by metadata](./managing-content#filtering-by-metadata) for the full operator list.
  </Info>
</ParamField>

<ParamField type="boolean">
  Toggle **ON** to enable advanced metadata filter expressions for more complex filtering logic.

  **Default:** `false`
</ParamField>

<ParamField type="boolean">
  Toggle **ON** to re-rank retrieved chunks before they are returned, improving result quality.

  **Default:** `false`
</ParamField>

***

### How the agent uses knowledge base

When a Custom Agent node executes with Knowledge Base enabled:

1. **Query generation**: The agent analyzes the user's input and generates a search query
2. **Chunk retrieval**: The Knowledge Base is queried using semantic search
3. **Relevance filtering**: Only chunks meeting the minimum relevance score are returned
4. **Context inclusion**: Retrieved chunks are added to the agent's context
5. **Response generation**: The agent generates a response using the retrieved information

```mermaid theme={"system"}
sequenceDiagram
    participant User
    participant Agent
    participant KB as Knowledge Base
    participant LLM
    
    User->>Agent: User query
    Agent->>KB: Search query
    KB->>Agent: Relevant chunks
    Agent->>LLM: Query + chunks
    LLM->>Agent: Generated response
    Agent->>User: Response with context
```

### ReAct model with knowledge base

When using the ReAct (Reasoning and Acting) model, the agent can:

* **Reason**: Determine if Knowledge Base information is needed
* **Act**: Query the Knowledge Base as a tool
* **Iterate**: Make multiple queries if needed for comprehensive answers

**Example ReAct flow:**

```
User: "What are the new features in version 2.5?"

Agent Reasoning: I need to search the Knowledge Base for version 2.5 information

Agent Action: Query Knowledge Base with "new features version 2.5"

Knowledge Base: Returns 3 relevant chunks about version 2.5 features

Agent Reasoning: I have enough information to answer the question

Agent Response: "Version 2.5 introduces three major features..."
```

## Viewing Knowledge Base results

When a Custom Agent node queries a Knowledge Base during a workflow run, you can inspect the retrieved chunks directly in the workflow run console.

### Knowledge Base tab

A **Knowledge Base** tab appears in the node console (alongside Logs, Input, Output, and Tools) when a node has KB results. For each Knowledge Base queried, the tab displays:

| Field                    | Description                                                            |
| ------------------------ | ---------------------------------------------------------------------- |
| **Knowledge Base name**  | The name of the queried KB (links to the KB data source configuration) |
| **Number of Results**    | The `topK` value used for the query                                    |
| **Min. Relevance Score** | The minimum relevance threshold (as a percentage)                      |
| **Chunks**               | Expandable list of retrieved chunks                                    |

Each chunk entry shows:

* **Relevance score** — how closely the chunk matches the query (percentage)
* **Store** — the name of the store the chunk belongs to
* **Chunk content** — the actual text (expandable, collapsed to 6 lines by default)
* **Submitted Content** — button to view the full chunk content in an overlay panel
* **Metadata** — any metadata associated with the chunk (if present)

<Tip>
  Use the Knowledge Base tab to debug retrieval quality. If the agent returns inaccurate answers, check whether the retrieved chunks contain the expected information and whether relevance scores are appropriate.
</Tip>

KB results also appear inline in the **Logs** tab for AI nodes and are aggregated at the workflow level in the overall workflow console.

***

## Example workflows

### Dynamic documentation updates

Update product documentation whenever a new release is deployed:

```yaml theme={"system"}
Workflow: Product Release
Nodes:
  1. Receive Release Data
  2. Knowledge Base Operation
     - KB: "Product Documentation KB"
     - Operation: "Replace Content"
     - Store: "Release Notes ${release.version}"
     - Content: "${release.documentation}"
  3. Notify Support Team
```

### Customer support with contextual AI

Use Knowledge Base in a customer support chatbot:

```yaml theme={"system"}
Workflow: Customer Support Chat
Nodes:
  1. Receive Customer Message
  2. Custom Agent Node
     - Model: GPT-4
     - Knowledge Base: "Support Documentation KB"
     - Min. Relevance: 75%
     - Max Results: 5
  3. Send Response to Customer
```

### Multi-source knowledge ingestion

Aggregate information from multiple systems:

```yaml theme={"system"}
Workflow: Weekly Knowledge Update
Nodes:
  1. Fetch from CRM System
  2. Append to KB
     - Store: "CRM Updates"
  3. Fetch from Documentation Site
  4. Append to KB
     - Store: "Documentation"
  5. Fetch from Support Tickets
  6. Append to KB
     - Store: "Support Insights"
```

## Error handling

### Common errors and solutions

<Accordion title="Store not found">
  **Error:** `Store "Example" does not exist in Knowledge Base "KB Name"`

  **Cause:** Attempting to append or replace content in a non-existent store

  **Solution:**

  * Verify the store name is correct
  * Use "Append Content" which creates the store if it doesn't exist
  * Check for typos in store names
</Accordion>

<Accordion title="Invalid JSON content">
  **Error:** `Failed to parse JSON content`

  **Cause:** The content provided is not valid JSON

  **Solution:**

  * Ensure workflow variables contain valid JSON
  * Validate JSON structure before passing to Knowledge Base operation
  * Check for special characters that may break JSON formatting
</Accordion>

<Accordion title="Knowledge Base not accessible">
  **Error:** `Knowledge Base "KB Name" not found or not accessible`

  **Cause:** The Knowledge Base doesn't exist or you don't have permissions

  **Solution:**

  * Verify the Knowledge Base exists in the project or dependencies
  * Check access permissions for the Knowledge Base
  * Ensure the Knowledge Base is published if using from dependencies
</Accordion>

<Accordion title="Chunking failed">
  **Error:** `Failed to process content into chunks`

  **Cause:** Error occurred while creating chunks from the content

  **Solution:**

  * Check console logs for detailed error messages
  * Verify the content is in the expected format
  * Retry the operation
  * Contact support if the issue persists
</Accordion>

## Best practices

### Agent configuration

<Tip>
  **Custom Agent with Knowledge Base:**

  * Start with a higher minimum relevance score (70-80%) to avoid irrelevant results
  * Adjust max results based on your use case (fewer for focused answers, more for comprehensive coverage)
  * Test different queries to understand chunk retrieval behavior
  * Monitor console logs to optimize configuration
</Tip>

### Relevance score management

<Tip>
  **Optimizing relevance scores:**

  * **Chunk size matters**: If chunks are too large and queries are small, relevance scores will be low because the query doesn't cover all the content. If you find yourself setting minimum relevance score to 0%, this may indicate your chunks are too large.
  * **Let the agent determine relevance**: Consider ordering chunks by relevance (descending) and letting the agent evaluate which chunks are relevant, rather than filtering by minimum relevance score. The agent can see if chunks are relevant and make better decisions.
  * **System prompt guidance**: If you want to manage relevance filtering, add instructions to your system prompt such as: "If you don't find any relevant information in the provided chunks, just say 'I cannot find this information'."
  * **Empty results handling**: The Knowledge Base tool returns an empty list when no results are found. Ensure your agent handles empty results gracefully and informs users when information is not available.
</Tip>

### Performance

<Tip>
  **Optimize performance:**

  * Keep stores focused and organized by topic
  * Add a metadata filter on the `source` system key when you know which store contains relevant information
  * Avoid ingesting extremely large documents without proper structuring
  * Regular cleanup of deprecated stores
  * **Consider removing max results limit**: Instead of limiting the number of chunks, order them by relevance (descending) and let the agent process all relevant chunks. This allows the agent to make better decisions about which information to use.
</Tip>

## Limitations

<Warning>
  **Current limitations:**

  * Only one Knowledge Base per Custom Agent node or Context Retrieval node
  * Cannot ingest documents directly from Document Plugin
  * Structured metadata filters cover common operators and AND/OR grouping. For filtering logic that cannot be expressed in the query builder (for example, arbitrary JSON expressions), toggle **Use advance metadata filters**.
</Warning>

## Using Context Retrieval nodes

The **Context Retrieval** node performs a standalone RAG search against a Knowledge Base and returns raw chunks without calling an LLM. This gives you full control over how retrieved information is used in your workflow.

### When to use Context Retrieval

* You need to inspect or filter chunks before passing them to an AI node
* You want to combine results from multiple Knowledge Bases
* You need chunk metadata (relevance scores, stores) for routing decisions
* You're building a multi-step RAG pipeline with custom processing between retrieval and generation

For full configuration details, see the [Context Retrieval node documentation](/5.9/ai-platform/agent-builder/context-retrieval).

***

## Next steps

<Card title="Managing Content" href="./managing-content" icon="folder">
  Understand store management in detail
</Card>

## Related resources

<CardGroup>
  <Card title="Custom Agent Nodes" href="../custom-agent-node" icon="robot">
    Complete guide to Custom Agent nodes
  </Card>

  <Card title="Context Retrieval" href="/5.9/ai-platform/agent-builder/context-retrieval" icon="magnifying-glass">
    Standalone Knowledge Base retrieval without LLM
  </Card>

  <Card title="Integration Designer" href="../integration-designer" icon="diagram-project">
    Overview of all workflow node types including Context Retrieval
  </Card>

  <Card title="Workflow Data Models" href="../workflow-data-models" icon="link">
    Understanding workflow variables and data
  </Card>
</CardGroup>


# MCP Data Sources
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source

Learn how to add, configure, and manage MCP servers as data sources in Integration Designer.

## Overview

This guide covers the complete lifecycle of working with MCP (Model Context Protocol) data sources in Integration Designer—from initial setup through ongoing tool management. Once configured, the MCP server's tools become available for use in Custom Agent nodes within your workflows.

## Prerequisites

Before adding an MCP data source, ensure you have:

* Access to Integration Designer with appropriate permissions
* MCP server URL and connection details
* Authentication credentials (if required)
* Knowledge of which tools you want to enable

<Info>
  Ensure you have the necessary permissions to access Integration Designer and manage data sources.
</Info>

## Adding an MCP server

### Step 1: Access Integration Designer

1. Open **FlowX Designer** and navigate to **General Settings**.
2. Select **Integration Designer** from the menu.
3. Click **Add Data Source**.

### Step 2: Select MCP server type

1. In the data source type selection, choose **MCP Server**.
2. A configuration form appears with required fields.

<Frame>
  ![Add MCP Data Source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp.png)
</Frame>

### Step 3: Configure basic information

<Steps>
  <Step title="Enter Name">
    Provide a unique name for the MCP server connection.
  </Step>

  <Step title="Add Description">
    (Optional) Provide a description of the MCP server's purpose and the tools it provides.

    This description is displayed in the MCP server details page and helps team members understand the integration's purpose.

    <Info>
      If not provided, the description will be autofillled after test connection is successful.
    </Info>
  </Step>

  <Step title="Configure Server URL">
    Enter the base URL of the MCP server.

    **Requirements:**

    * **Required**: URL cannot be empty
    * **Format**: Must be a valid URL (e.g., `https://api.example.com/mcp`)
    * **Multiple Connections**: You can create multiple connections to the same MCP server with different configurations

    **Example URLs:**

    ```
    https://api.githubcopilot.com/mcp/
    https://mcp.figma.com/mcp
    https://mcp.intercom.com/sse
    ```
  </Step>
</Steps>

<Frame>
  ![MCP Server Basic Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp1.png)
</Frame>

### Step 4: Configure authentication

Select the appropriate authentication method for your MCP server:

<Tabs>
  <Tab title="None">
    No authentication required. The MCP server accepts requests without credentials.

    **Use case**: Development environments, public MCP servers, or servers with network-level security.

    **Configuration**: No additional fields required.
  </Tab>

  <Tab title="Basic Auth">
    Username and password authentication.

    **Use case**: MCP servers with simple authentication requirements.

    **Required fields:**

    <ParamField type="string">
      The username for authentication.
    </ParamField>

    <ParamField type="string">
      The password for authentication. Stored securely.
    </ParamField>
  </Tab>

  <Tab title="Bearer Token">
    Static token-based authentication sent in the Authorization header.

    **Use case**: MCP servers that accept pre-generated access tokens or API keys.

    **Required fields:**

    <ParamField type="string">
      The bearer token value. Stored securely.
    </ParamField>
  </Tab>

  <Tab title="API Key">
    Key-based authentication sent via a header or query parameter.

    **Use case**: Third-party API services that use API key authentication.

    **Required fields:**

    <ParamField type="string">
      The API key value. Stored securely.
    </ParamField>
  </Tab>

  <Tab title="OAuth2 Client Credentials">
    OAuth 2.0 service account authentication using the **client credentials flow**.

    **Use case**: Production environments requiring secure service-to-service authentication.

    **Required fields:**

    <ParamField type="string">
      The OAuth 2.0 client identifier provided by your identity provider.
    </ParamField>

    <ParamField type="string">
      The OAuth 2.0 client secret. This is encrypted and stored securely.
    </ParamField>

    <ParamField type="string">
      The URL of your OAuth 2.0 authorization server (e.g., `https://auth.example.com/oauth/token`).
    </ParamField>

    <Frame>
      ![MCP Service Account Authentication](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp3.png)
    </Frame>
  </Tab>

  <Tab title="OAuth2 User">
    OAuth 2.0 authentication that carries user identity context, using a redirect URI for authorization.

    **Use case**: Operations that require the end-user's identity for access control or auditing.

    **Required fields:**

    <ParamField type="string">
      The OAuth 2.0 client identifier.
    </ParamField>

    <ParamField type="string">
      The OAuth 2.0 client secret.
    </ParamField>

    <ParamField type="string">
      The authorization server endpoint.
    </ParamField>

    <ParamField type="string">
      The redirect URI for the OAuth2 authorization flow.
    </ParamField>
  </Tab>
</Tabs>

### Step 5: Test connection

Before saving the MCP data source, test the connection to verify it's configured correctly.

1. Click **Test Connection** button.
2. The system attempts to connect to the MCP server using the provided configuration.
3. Wait for the connection test result:

**Success Response:**

```json theme={"system"}
{
  "status": 200,
  "message": "Connection successful"
}
```

<Check>
  If the connection test succeeds, you can proceed to save the data source. If it fails, review the error message and verify your configuration.
</Check>

<Frame>
  ![Successful Connection Test](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp4.png)
</Frame>

### Step 6: Save and view tools

1. After a successful connection test, click **Create**.
2. The MCP server is persisted as a data source.
3. You are automatically redirected to the MCP server details page, where available tools are displayed.

<Info>
  By default, all tools exposed by the MCP server are enabled. You can turn off specific tools from the MCP server details page.
</Info>

## MCP server details page

After successfully adding an MCP server, the details page displays:

### Header Information

* **Title**: The name you assigned to the MCP server
* **Subtitle**: Description and server URL (trimmed to one row)
  * Click to view full description in a modal

<Frame>
  ![MCP Server Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp5.png)
</Frame>

### Tools tab

The Tools tab displays all available tools from the MCP server and allows you to manage which tools are available for use in Custom Agent nodes.

<Frame>
  ![MCP Tools Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp6.png)
</Frame>

#### Understanding tool information

Each tool in the MCP server displays the following information:

<ParamField type="string">
  The unique identifier for the tool. This name is used when the AI agent invokes the tool.
</ParamField>

<ParamField type="string">
  A brief description of what the tool does. This helps users understand the tool's purpose and when to use it.
</ParamField>

<ParamField type="boolean">
  Indicates whether the tool is currently enabled (available to AI agents) or disabled (not available).

  * **Enabled**: Tool can be used in Custom Agent nodes
  * **Disabled**: Tool is hidden from Custom Agent node configuration
</ParamField>

#### Viewing tool details

To view complete details about a tool:

1. Click on any tool row in the Tools tab
2. A modal window opens displaying:

<Accordion title="Tool Name">
  The complete name of the tool as registered in the MCP server.
</Accordion>

<Accordion title="Description">
  Full description of the tool's functionality, including:

  * What the tool does
  * When to use it
  * Expected behavior
</Accordion>

<Frame>
  ![MCP Tool Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp6.png)
</Frame>

<Accordion title="Input Schema">
  JSON Schema defining the expected input parameters for the tool.

  **Example:**

  ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "customerId": {
          "type": "string",
          "description": "The unique identifier for the customer"
        },
        "includeOrders": {
          "type": "boolean",
          "description": "Whether to include order history",
          "default": false
        }
      },
      "required": ["customerId"]
    }
  ```

  <Info>
    The input schema is used by AI agents to understand what parameters the tool expects and how to format requests.
  </Info>
</Accordion>

<Accordion title="Output Schema (Optional)">
  JSON Schema defining the structure of the tool's response.

  **Example:**

  ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "customer": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "name": { "type": "string" },
            "email": { "type": "string" }
          }
        },
        "orders": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "orderId": { "type": "string" },
              "total": { "type": "number" }
            }
          }
        }
      }
    }
  ```

  <Info>
    Output schemas are optional. If not provided, the AI agent will work with the actual response structure returned by the tool.
  </Info>
</Accordion>

<Frame>
  ![MCP Tool Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp7.png)
</Frame>

#### Enabling and disabling tools

You can control which tools are available for use in Custom Agent nodes by enabling or disabling them.

**Enable/Disable Individual Tools:**

<Steps>
  <Step title="Access Tool Menu">
    In the Tools tab, locate the tool you want to enable or disable.
  </Step>

  <Step title="Toggle Tool Status">
    * Click the three-dot menu (⋯) at the end of the tool row
    * Select **Enable** or **Disable** from the menu
  </Step>

  <Step title="Confirm Change">
    The tool's status updates immediately. Enabled tools show a green status indicator, while disabled tools show a gray indicator.
  </Step>
</Steps>

<Frame>
  ![Enable/Disable Tools Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp8.png)
</Frame>

<Warning>
  Disabling tools that are currently in use by active workflows may affect those workflows. Always verify that tools are not in use before disabling them.
</Warning>

### Authorization tab

The Authorization tab displays the current authentication configuration:

* **Authentication Type**: None, Basic Auth, Bearer Token, API Key, OAuth2 Client Credentials, or OAuth2 User
* **Configuration Details**: Relevant fields for the selected auth type (sensitive information like secrets and tokens are hidden)

<Warning>
  Changes to authentication settings require re-testing the connection and may affect existing workflows using this MCP server.
</Warning>

<Frame>
  ![Authorization Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp9.png)
</Frame>

## Managing tools

### Refreshing tools from MCP server

Tools are automatically synchronized from the MCP server when you:

* Initially connect the MCP server
* Re-test the connection from the Authorization tab
* Manually refresh the tools list

To manually refresh tools:

1. Navigate to the MCP server details page
2. Go to the **Authorization** tab
3. Click **Check for Updates**
4. If successful, return to the **Tools** tab to see any new or updated tools

<Info>
  Tool definitions (name, description, schemas) are read-only and managed by the MCP server. You can only control the enabled/disabled status from Integration Designer.
</Info>

### API endpoint for tool management

Tools can also be managed programmatically using the API:

**Enable/Disable Tool API:**

```http theme={"system"}
POST /api/systems/tool/{toolId}/enable?resourceId={resourceId}
```

Required header: `X-Workspace-Id: {workspaceId}`

**Request Body:**

```json theme={"system"}
{
  "enabled": true
}
```

**Response:**

```json theme={"system"}
{
  "status": 200,
  "message": "Tool status updated successfully",
  "tool": {
    "id": "67d816adacc8b761ebf769e5",
    "name": "get_customer",
    "enabled": true
  }
}
```

<Info>
  For complete API documentation, see [MCP API Reference](../../../api/mcp-api-reference).
</Info>

### Monitoring tool usage

To understand which tools are being used in your workflows:

1. Navigate to the **Run Logs** section after running a workflow
2. Check the **Tools** tab (visible when MCP tools are used)
3. Review which tools were invoked and their execution details

<Frame>
  ![Tool Usage Monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/run_logs.png)
</Frame>

## Managing multiple MCP connections

You can create multiple connections to the same MCP server with different configurations:

**Use Cases:**

* Different authentication credentials for different environments
* Separate tool configurations for different use cases
* Testing vs. production instances

**Example:**

```
- CRM Production (https://api.crm.com) - Service Account Auth
- CRM Development (https://api.crm.com) - No Auth
- CRM Testing (https://api.crm.com) - Different Service Account
```

## Validation rules summary

<Accordion title="Name Validation">
  * **Required**: ✅ Yes
  * **Unique**: ✅ Within project
  * **Allowed Characters**: Letters, numbers, `[]`, `()`, `.`, `_`, `-`
  * **Error Message**: "Name must be unique inside the project." or "Name can only contain letters, numbers and the following special characters \[] () . \_ -"
</Accordion>

<Accordion title="Description Validation">
  * **Required**: ❌ No
  * **Max Length**: No explicit limit (trimmed in UI display)
</Accordion>

<Accordion title="Server URL Validation">
  * **Required**: ✅ Yes
  * **Unique**: ❌ No (multiple connections allowed)
  * **Format**: Valid URL with protocol (http/https)
</Accordion>

<Accordion title="Authentication Validation">
  * **Required Fields**: Depends on authentication type selected
  * **Service Account**: All three fields (Client ID, Client Secret, Identity Provider URL) are required
</Accordion>

## Best practices

### Data source setup

<Check>
  **Test Before Saving**: Always test the connection before saving an MCP data source to ensure the configuration is correct.
</Check>

<Check>
  **Use Descriptive Names**: Choose clear, descriptive names that indicate the MCP server's purpose and environment (e.g., "CRM-Production", "Analytics-Dev").
</Check>

<Check>
  **Document Purpose**: Add detailed descriptions to help team members understand what the MCP server provides and when to use it.
</Check>

<Check>
  **Secure Authentication**: Use Service Account authentication for production environments to ensure secure access.
</Check>

### Tool management

<Check>
  **Start with All Enabled**: By default, all tools are enabled. Review the available tools and disable only those you don't need.
</Check>

<Check>
  **Regular Audits**: Periodically review enabled tools to ensure they're still needed and being used effectively.
</Check>

<Check>
  **Security Considerations**: Disable tools that provide access to sensitive data or operations if they're not needed for your use case.
</Check>

### Workflow impact considerations

Before disabling tools, consider the following:

1. **Check Tool Usage**: Verify if the tool is currently used in any active workflows
2. **Impact Assessment**: Understand what workflows might be affected
3. **Communication**: Notify team members before disabling tools that might be in use
4. **Testing**: Test workflows after re-enabling tools to ensure they work as expected

<Warning>
  If you disable a tool that's referenced in a Custom Agent node, that node will not be able to use the tool during execution. The AI agent will work with the remaining enabled tools only.
</Warning>

## Common issues and troubleshooting

<AccordionGroup>
  <Accordion title="Connection Test Fails">
    **Possible Causes:**

    * Invalid server URL
    * Incorrect authentication credentials
    * Network connectivity issues
    * MCP server is down or unreachable

    **Solutions:**

    * Verify the server URL is correct and accessible
    * Check authentication credentials with your MCP server administrator
    * Test network connectivity to the MCP server
    * Confirm the MCP server is running and accepting connections
  </Accordion>

  <Accordion title="No Tools Displayed">
    **Possible Causes:**

    * MCP server hasn't exposed any tools
    * Connection issue after initial setup

    **Solutions:**

    * Verify the MCP server is configured to expose tools
    * Re-test the connection from the Authorization tab
    * Contact your MCP server administrator
  </Accordion>

  <Accordion title="Name Validation Error">
    **Error**: "Name must be unique inside the project."

    **Solution**: Choose a different name that hasn't been used in this project.

    ***

    **Error**: "Name can only contain letters, numbers and the following special characters \[] () . \_ -"

    **Solution**: Remove any special characters that aren't in the allowed list.
  </Accordion>

  <Accordion title="New Tools Not Appearing">
    **Problem**: You added new tools to your MCP server, but they don't appear in Integration Designer.

    **Solution**:

    1. Go to the Authorization tab
    2. Click **Test Connection** to refresh the tool list
    3. Return to the Tools tab to see the new tools
  </Accordion>

  <Accordion title="Tool Used in Active Workflow">
    **Problem**: You want to disable a tool, but it's used in an active workflow.

    **Solution**:

    1. Search for workflows using the tool
    2. Update those workflows to use alternative tools or remove the MCP server reference
    3. Test the modified workflows
    4. Disable the tool once it's no longer in use
  </Accordion>

  <Accordion title="Re-enabling a Previously Disabled Tool">
    **Problem**: You disabled a tool and now need to re-enable it.

    **Solution**:

    1. Find the tool in the Tools tab (disabled tools are still listed)
    2. Click the toggle or menu to enable it
    3. Test workflows that use this tool to ensure they work correctly
  </Accordion>

  <Accordion title="Tool Schema Changes">
    **Problem**: The MCP server updated a tool's input or output schema.

    **Solution**:

    1. Test the MCP connection to refresh tool definitions
    2. Review the updated schema in the tool details modal
    3. Update any Custom Agent nodes that use this tool to match the new schema
    4. Test affected workflows
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="Custom Agent Node" href="../custom-agent-node" icon="robot">
  Learn how to use MCP tools in workflows with Custom Agent nodes
</Card>

## Related resources

<CardGroup>
  <Card title="MCP Integration Overview" href="./mcp-integration-overview" icon="link">
    Learn about MCP integration capabilities
  </Card>

  <Card title="MCP API Reference" href="../../../api/mcp-api-reference" icon="code">
    View API documentation for programmatic access
  </Card>

  <Card title="Integration Designer course" icon="graduation-cap" href="https://academy.flowx.ai/explore/integration-designer">
    Hands-on course covering data sources including MCP server integration
  </Card>
</CardGroup>


# MCP integration
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview

Learn how to integrate Model Context Protocol (MCP) servers with FlowX.AI to enable AI agents to use external tools and services.

## Overview

The Model Context Protocol (MCP) integration connects FlowX.AI with external MCP servers and exposes their tools to AI agents. AI agents can interact with external systems, databases, APIs, and services through this protocol.

<Info>
  MCP is a protocol for AI agents to access external tools and data sources.
</Info>

## Key features

* Connect MCP servers as data sources in Integration Designer
* Enable or turn off specific tools exposed by MCP servers
* Use MCP tools in workflow processes through Custom Agent nodes
* Secure connections with multiple authentication methods
* Monitor tool usage and execution details in console logs

## How it works

```mermaid theme={"system"}
graph LR
    A[Integration Designer] -->|Connect| B[MCP Server]
    B -->|Expose Tools| C[Tool Registry]
    C -->|Select Tools| D[Custom Agent Node]
    D -->|Execute| E[AI Service]
    E -->|Use Tools| B
```

### High-level workflow

1. **Add MCP server**: Configure an MCP server connection as a data source in Integration Designer
2. **Authorize access**: Authenticate the connection using supported authentication methods
3. **Manage tools**: View and enable or turn off available tools from the MCP server
4. **Use in workflows**: Add Custom Agent nodes to workflows and select which MCP servers to use
5. **Execute and monitor**: Run workflows and track tool usage in console logs

## Supported protocols and features

<Info>
  The MCP integration is actively being developed. The features listed below represent the current capabilities. Additional protocol support and authentication methods will be added in future releases.
</Info>

### Transport protocols

The following transport protocols are currently supported:

<Accordion title="SSE (Server-Sent Events)">
  Server-Sent Events protocol for real-time, unidirectional communication from the MCP server to FlowX.AI.

  **Use Case**: Ideal for streaming responses and long-running operations where the server needs to push updates to the client.
</Accordion>

<Accordion title="Streamable HTTP">
  HTTP-based streaming protocol for receiving data in chunks over a persistent connection.

  **Use Case**: Suitable for large data transfers and scenarios where you need progressive response handling.
</Accordion>

### Proxy support

MCP connections support inline proxy configuration for environments that require routing through a proxy server. This is configured directly on each MCP data source connection.

| Setting                | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| **Protocol**           | HTTP, HTTPS, SOCKS4, or SOCKS5                          |
| **Host and port**      | Proxy server address                                    |
| **Authentication**     | Optional basic authentication for the proxy             |
| **No-proxy patterns**  | Bypass list for addresses that should not use the proxy |
| **SSL verification**   | Toggle SSL/TLS certificate verification                 |
| **Connection timeout** | Configurable timeout for proxy connections              |

<Note>
  This is separate from the reusable [Proxy connections](../proxy-connections) resource available for RESTful System data sources. MCP data sources use their own inline proxy configuration.
</Note>

***

## Authentication methods

MCP integrations support the following authentication methods:

| Method                        | Description                                            | Use case                                     |
| ----------------------------- | ------------------------------------------------------ | -------------------------------------------- |
| **None**                      | No authentication                                      | Public MCP servers, development environments |
| **Basic Auth**                | Username and password                                  | Simple authentication requirements           |
| **Bearer Token**              | Static token-based authentication                      | API key or pre-generated token access        |
| **API Key**                   | Key-based authentication via header or query parameter | Third-party API access                       |
| **OAuth2 Client Credentials** | Service account authentication                         | Production service-to-service communication  |
| **OAuth2 User**               | User-context OAuth2 with redirect URI                  | Operations requiring user identity context   |

<Info>
  The authentication type is selected during MCP server setup and can be discovered automatically during connection testing using the **Supported Auth Discovery** feature.
</Info>

## Use cases

### External API integration

Connect to external APIs and services through MCP tools. AI agents can fetch data, trigger actions, and integrate with third-party systems.

### Database operations

Query databases, retrieve records, and perform data operations through MCP tools.

### Custom business logic

Expose custom business logic as MCP tools for AI agents to execute.

### Multi-system orchestration

Use multiple MCP servers in a single Custom Agent node to orchestrate operations across different systems.

## Next steps

<CardGroup>
  <Card title="MCP Data Sources" href="./adding-mcp-data-source" icon="database">
    Add, configure, and manage MCP servers and their tools
  </Card>

  <Card title="Custom Agent Node" href="../custom-agent-node" icon="robot">
    Use MCP tools in workflows with Custom Agent nodes
  </Card>

  <Card title="MCP API Reference" href="../../../api/mcp-api-reference" icon="code">
    API documentation for MCP integration
  </Card>
</CardGroup>

## Related resources

<Card title="Integration Designer" href="../../integration-designer/designer-overview" icon="link">
  Integration Designer and data sources
</Card>

<Card title="Integrations Overview" href="../../integrations-overview" icon="link">
  Integration ecosystem overview
</Card>


# Microsoft Outlook
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source

Connect to Microsoft Outlook via MS Graph API to read and send emails directly from your FlowX.AI processes, using Azure AD authentication for native Outlook integration.

## Overview

Microsoft Outlook is a data source type in Integration Designer that provides native Outlook connectivity through the Microsoft Graph API. Unlike the [Email Trigger](./email-trigger) (IMAP) and [Email Sender](./email-sender) (SMTP) data sources, Microsoft Outlook uses Azure AD authentication and the MS Graph API for a unified read and send experience.

Use cases include:

* **Email-triggered workflows**: Automatically start processes when emails arrive in an Outlook mailbox
* **Customer communication**: Send emails and replies directly from business processes
* **Document processing**: Trigger workflows when emails with attachments are received
* **Unified inbox management**: Read and send from the same data source configuration

<Info>
  Microsoft Outlook supports three scope modes:

  * **Read Emails** — monitor a mailbox and trigger processes
  * **Send Emails** — send emails from processes via notification templates
  * **Read & Send Emails** — both capabilities in a single data source
</Info>

### When to use Microsoft Outlook vs Email Trigger / Email Sender

FlowX.AI offers two ways to connect to email: **Microsoft Outlook** (MS Graph API) and **Email Trigger** / **Email Sender** (IMAP/SMTP). Choose based on your mail provider and requirements.

|                      | Microsoft Outlook                                                  | Email Trigger + Email Sender                           |
| -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Protocol**         | MS Graph API                                                       | IMAP (read) + SMTP (send)                              |
| **Authentication**   | Azure AD (client credentials)                                      | Username + password / app password                     |
| **Read + Send**      | Single data source (Read & Send scope)                             | Two separate data sources                              |
| **Reply threading**  | Native — uses MS Graph message ID to maintain conversation threads | Manual — requires `Message-ID` header forwarding       |
| **Provider support** | Microsoft 365 / Outlook only                                       | Any IMAP/SMTP-compatible mail server                   |
| **Best for**         | Organizations using Microsoft 365                                  | Gmail, self-hosted mail servers, or mixed environments |

<Tip>
  If your organization uses Microsoft 365, the Outlook data source is the recommended approach. It simplifies configuration by combining read and send into a single data source with Azure AD authentication.
</Tip>

***

## How it works

<Steps>
  <Step title="Register an Azure AD app">
    Create an app registration in Azure AD with the required MS Graph permissions for your scope.
  </Step>

  <Step title="Create a Microsoft Outlook data source">
    Configure the connection in Integration Designer with your Azure AD credentials and select the desired scope.
  </Step>

  <Step title="Connect to processes">
    For **Read** scope: link to a Message Start Event node and activate from Manage Triggers.
    For **Send** scope: link to a notification template and use the Send Notification action.
  </Step>

  <Step title="Process emails">
    FlowX.AI monitors the mailbox (Read) or sends emails (Send) through the MS Graph API.
  </Step>
</Steps>

***

## Creating a Microsoft Outlook data source

<Frame>
  ![Add Data Source - Microsoft Outlook](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_outlook_form.png)
</Frame>

### Prerequisites

Before configuring a Microsoft Outlook data source, ensure you have:

* Access to Integration Designer with appropriate permissions
* An Azure AD app registration with the required MS Graph API permissions:

| Scope                  | Required permissions (any one)                     |
| ---------------------- | -------------------------------------------------- |
| **Read Emails**        | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
| **Send Emails**        | `Mail.Send` or `Mail.ReadWrite`                    |
| **Read & Send Emails** | One read permission + one send permission          |

* Azure AD credentials: **Tenant ID**, **Client ID**, and **Client Secret**

<Warning>
  MS Graph permissions must be configured as **Application permissions** (not Delegated) in your Azure AD app registration, since the connection uses client credentials flow.
</Warning>

### Step 1: Access Integration Designer

1. Navigate to **FlowX Designer** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources**
2. Click the **+** button to open the **Add Data Source** dialog
3. Select **Microsoft Outlook** as the data source type

### Step 2: Configure authentication

<ParamField type="string">
  The Azure AD tenant ID for your organization.

  <Tip>
    This field accepts configuration parameters. Use `${configParam}` syntax to reference environment-specific values.
  </Tip>
</ParamField>

<ParamField type="string">
  The application (client) ID from your Azure AD app registration.

  <Tip>
    This field accepts configuration parameters for environment-specific credentials.
  </Tip>
</ParamField>

<ParamField type="string">
  The client secret generated in your Azure AD app registration.

  <Tip>
    Store sensitive credentials in configuration parameters and reference them here using `${configParam}` syntax.
  </Tip>
</ParamField>

### Step 3: Test the connection

Click the **Test Connection** button to verify your Azure AD credentials:

| Result    | Message                          | Action                                     |
| --------- | -------------------------------- | ------------------------------------------ |
| ✅ Success | "Established connection"         | Proceed to configure scope                 |
| ❌ Error   | "Failed to establish connection" | Check Azure AD credentials and permissions |

<Info>
  The data source can be created even if the test connection fails. If the test fails on creation, you will be redirected to the **Authorization** tab with a failed connection message instead of the **Settings** page.
</Info>

### Step 4: Configure scope and email

<ParamField type="select">
  The email capabilities for this data source:

  | Option                 | Description                                                |
  | ---------------------- | ---------------------------------------------------------- |
  | **Read Emails**        | Monitor a mailbox and trigger processes when emails arrive |
  | **Send Emails**        | Send emails from processes via notification templates      |
  | **Read & Send Emails** | Both read and send capabilities                            |
</ParamField>

<ParamField type="string">
  The email address of the mailbox to monitor or send from.

  **Validation:** Must be a valid email format.

  <Tip>
    This field accepts configuration parameters for environment-specific values.
  </Tip>
</ParamField>

### Step 5: Name and description

<ParamField type="string">
  A unique, descriptive name for the Microsoft Outlook data source.

  **Validation rules:**

  * Required field
  * Must be unique within the project
  * Only letters, numbers, and these characters allowed: `[]`, `()`, `.`, `_`, `-`
  * Minimum 3 characters, maximum 50 characters
</ParamField>

<ParamField type="string">
  Optional description explaining the purpose of this data source.
</ParamField>

Click **Create** to save the data source.

***

## Settings page

After creating the data source, configure monitoring and validation settings in the **Settings** tab. The available settings depend on the selected scope.

<Frame>
  ![Microsoft Outlook - Settings tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ms_outlook_settings.png)
</Frame>

### Read scope settings

For data sources with **Read Emails** or **Read & Send Emails** scope:

#### Filtering criteria

<ParamField type="string">
  The email address that will be monitored. Editable after creation.

  <Tip>
    This field accepts configuration parameters.
  </Tip>
</ParamField>

<ParamField type="string">
  The mailbox folder to monitor for incoming emails.

  **Default:** `Inbox`

  Supported well-known folder names:

  * `Inbox`, `Sent`, `Drafts`, `Deleted`, `Junk`, `Archive`, `Outbox`

  <Tip>
    This field accepts configuration parameters for environment-specific folder names.
  </Tip>
</ParamField>

<ParamField type="string">
  Displays the scope selected during creation. This field is read-only.
</ParamField>

#### Attachment validations

Toggle **ON** the **Add validations to Attachments** option to configure validation rules for incoming email attachments.

<Frame>
  ![Microsoft Outlook - Attachment validations](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ms_outlook_validations.png)
</Frame>

<Info>
  If any validation fails, the email will not be processed and a warning will appear in the **Failed Triggers** section in Runtime.
</Info>

<ParamField type="array">
  Restrict which attachment file types are accepted:

  | Type     | Extensions                               |
  | -------- | ---------------------------------------- |
  | PDF      | `.pdf`                                   |
  | DOCUMENT | `.doc`, `.docx`, `.txt`                  |
  | IMAGE    | `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff` |
  | EXCEL    | `.xls`, `.xlsx`, `.csv`                  |
  | ZIP      | `.zip`                                   |

  <Info>
    Leave empty to accept all file types.
  </Info>
</ParamField>

<ParamField type="number">
  Maximum allowed size per attachment file.

  **Maximum:** 25 MB
</ParamField>

<ParamField type="number">
  Maximum number of attachments allowed per email.
</ParamField>

<Tip>
  All fields in the Settings section accept configuration parameters, enabling environment-specific configurations.
</Tip>

### Send scope settings

For data sources with **Send Emails** scope only, the Settings tab shows a simplified view:

<ParamField type="string">
  The email address used as the sender ("From" address) for outgoing emails.
</ParamField>

<ParamField type="string">
  Displays the scope selected during creation. This field is read-only.
</ParamField>

<Info>
  Send-only data sources do not display the **Mailbox Folder** or **Attachment Validations** fields, since those apply only to the Read scope. Sent emails are automatically saved to the Sent Items folder.
</Info>

***

## Authorization page

<Frame>
  ![Microsoft Outlook - Authorization tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ms_outlook_auth.png)
</Frame>

The **Authorization** tab displays the Azure AD credentials and allows you to update them or re-test the connection:

<ParamField type="string">
  Azure AD tenant ID.
</ParamField>

<ParamField type="string">
  Azure AD application (client) ID.
</ParamField>

<ParamField type="string">
  Azure AD client secret.
</ParamField>

Click **Test Connection** to verify the credentials. The test validates both the authentication and the required MS Graph permissions for the configured scope.

***

## Connecting to processes

### Reading emails (process trigger)

To trigger processes when emails arrive:

<Steps>
  <Step title="Configure the Message Start Event">
    Open your process definition and add a **Message Start Event** (Start Catch Message) node.
  </Step>

  <Step title="Select Microsoft Outlook as trigger type">
    In the node configuration, set **Trigger Type** to **Microsoft Outlook**. Then select the Microsoft Outlook data source (only data sources with **Read** or **Read & Send** scope are shown).
  </Step>

  <Step title="Activate the trigger">
    Navigate to **Runtime Settings** → **Manage Triggers** and activate the trigger.
  </Step>
</Steps>

<Frame>
  ![Message Start Event - Microsoft Outlook trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/email_trigger.png)
</Frame>

<Warning>
  The trigger must be activated from **Manage Triggers** in Runtime Settings before email monitoring begins.
</Warning>

<Info>
  The Microsoft Outlook data source polls for new emails every **30 seconds** by default, using the same polling scheduler as the Email Trigger (configurable via `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL`). Each polling cycle processes up to **50 messages** (configurable via `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL`). Emails with the same timestamp as the last processed email are deduplicated automatically using their internet message ID.
</Info>

### Sending emails (notification template)

To send emails from processes:

<Steps>
  <Step title="Link to a notification template">
    Open a notification template and set **Email Server** to **Predefined Email Connection**. Select the Microsoft Outlook data source (only data sources with **Send** or **Read & Send** scope are shown).
  </Step>

  <Step title="Add a Send Notification action">
    Add a [Send Notification](../../building-blocks/actions/send-notification-action) action to a process node and select the notification template.
  </Step>
</Steps>

<Frame>
  ![Notification template - Outlook data source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/template.png)
</Frame>

### Replying to received emails

Microsoft Outlook supports replying to emails received via the Read scope, maintaining the original conversation thread in the recipient's inbox.

<Steps>
  <Step title="Configure the Send Notification action">
    Add a [Send Notification](../../building-blocks/actions/send-notification-action) action to a process node. In the action configuration, turn on the **Reply to received emails** toggle.
  </Step>

  <Step title="Set the Reply to Email Header">
    Specify the process key that holds the original email's header parameters (e.g., `emailMessage.headerParams`). This is required when the reply toggle is on.
  </Step>

  <Step title="Configure recipients (optional)">
    By default, the reply is sent to the original sender. You can override this by adding explicit **Receivers**, **CC**, or **BCC** addresses. Duplicate recipients are automatically removed.
  </Step>
</Steps>

<Info>
  The reply mechanism uses the `x-ms-graph-message-id` header from the original email to thread the reply correctly. If this header is not available, the system falls back to the standard `Message-ID` header and looks up the original message via the MS Graph API. Sent replies are automatically saved to the Sent Items folder.
</Info>

***

## Email data schema

When an email triggers a process, the following data structure is available in your process variables:

```json theme={"system"}
{
  "emailMessage": {
    "subject": "Support Request #12345",
    "dateTime": "2026-01-15T10:30:00Z",
    "sender": "customer@example.com",
    "body": "Email body content...",
    "fileAttachments": [
      {
        "filePath": "email-attachments/proc-123/invoice.pdf",
        "downloadPath": "/api/internal/files/uuid-456/download"
      }
    ],
    "headerParams": {
      "Message-ID": "<abc123@example.com>",
      "x-ms-graph-message-id": "AAMk..."
    }
  }
}
```

### Schema fields

| Field                                | Type              | Description                            |
| ------------------------------------ | ----------------- | -------------------------------------- |
| `subject`                            | string            | Email subject line                     |
| `dateTime`                           | string (ISO 8601) | Timestamp when email was received      |
| `sender`                             | string            | Sender's email address                 |
| `body`                               | string            | Email body content                     |
| `fileAttachments`                    | array             | List of attachment metadata objects    |
| `fileAttachments[].filePath`         | string            | Storage path in Document Plugin        |
| `fileAttachments[].downloadPath`     | string            | API path to download the file          |
| `headerParams.Message-ID`            | string            | Standard email message identifier      |
| `headerParams.x-ms-graph-message-id` | string            | MS Graph message ID (used for replies) |

***

## Managing triggers at runtime

### Manage Triggers

Navigate to **Runtime Settings** → **Manage Triggers** to view and control Microsoft Outlook email triggers.

<Frame>
  ![Manage Triggers - Microsoft Outlook](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/triggers.png)
</Frame>

| Column           | Description                                          |
| ---------------- | ---------------------------------------------------- |
| **State**        | Current status: `Active` or `Inactive`               |
| **Process Name** | The process definition linked to this trigger        |
| **Trigger Type** | "Email Trigger" for Microsoft Outlook email triggers |
| **Event Name**   | The Microsoft Outlook data source name               |
| **Location**     | Project and branch information                       |

### Activation requirements

For a Microsoft Outlook trigger to appear in Manage Triggers:

1. Microsoft Outlook data source must be created with **Read** or **Read & Send** scope
2. Data source must be linked to a Message Start Event node
3. The process must be part of a build in the **Active Policy**

### Failed Triggers

When emails fail validation or processing errors occur, they appear in the **Failed Triggers** section under **Runtime Settings**.

Failed triggers display the timestamp, trigger name, cause type, context (e.g., sender address), and detailed error messages. Click a row to open the details page with full diagnostic information.

#### Common failure causes

<Tabs>
  <Tab title="File type not permitted">
    **Message:** "The file `{filename}` could not be uploaded because it is not on the list of permitted file types."

    **Resolution:** Update the **Allowed File Types** in the data source Settings tab, or ask the sender to use an accepted format.
  </Tab>

  <Tab title="File size exceeded">
    **Message:** "`{filename}` is too large. Maximum allowed: 25 MB"

    **Resolution:** The attachment exceeds the configured maximum file size. Ask the sender to reduce the file size.
  </Tab>

  <Tab title="File count exceeded">
    **Message:** "File limit exceeded. For this trigger there is a limit of `{limit}` per email."

    **Resolution:** The email has more attachments than allowed. Ask the sender to split attachments across multiple emails.
  </Tab>

  <Tab title="Authentication failure">
    **Message:** "MS Graph connection failed: \[error details]"

    **Resolution:** Azure AD credentials may have expired or been revoked. The system retries once on 401/403 errors by refreshing the cached client. If the retry also fails, go to the **Authorization** tab, verify the Tenant ID, Client ID, and Client Secret, and click **Test Connection**. Regenerate the client secret in Azure AD if it has expired.
  </Tab>

  <Tab title="Missing permissions">
    **Message:** "MS Graph application is missing required permissions: \[list]. Please add these as Application permissions in Azure AD and grant admin consent."

    **Resolution:** The Azure AD app registration is missing one or more required MS Graph permissions. Add the listed permissions as **Application permissions** (not Delegated) in the Azure portal and ensure **admin consent** has been granted.
  </Tab>
</Tabs>

***

## Use case: document processing with auto-reply

This example walks through a complete email-triggered workflow: an email with an attachment arrives, the process extracts and classifies the document, then replies to the sender with a confirmation.

<Steps>
  <Step title="Create a Microsoft Outlook data source">
    Configure a data source with **Read & Send Emails** scope, pointed at your intake mailbox (e.g., `documents@company.com`). Set attachment validations to accept PDF and DOCUMENT types with a 25 MB size limit.
  </Step>

  <Step title="Design the process">
    Create a process with a **Message Start Event** node configured to trigger from the Outlook data source. The email data is available in process variables under `emailMessage`.
  </Step>

  <Step title="Access email data in downstream nodes">
    Use the email schema fields in Script or Business Rule nodes to route the process:

    ```javascript theme={"system"}
    // Access email fields in a Script node
    var subject = input.get("emailMessage").get("subject");
    var sender = input.get("emailMessage").get("sender");
    var attachments = input.get("emailMessage").get("fileAttachments");

    // Route based on subject keywords
    if (subject.contains("invoice")) {
        output.put("documentType", "INVOICE");
    } else {
        output.put("documentType", "GENERAL");
    }
    ```
  </Step>

  <Step title="Process the attachment">
    Use the `fileAttachments[].downloadPath` to retrieve the file from the Document Plugin for classification, data extraction, or storage.
  </Step>

  <Step title="Reply to the sender">
    Add a **Send Notification** action with the **Reply to received emails** toggle turned on. Set the reply header to `emailMessage.headerParams`. The reply is threaded under the original email in the sender's inbox.
  </Step>

  <Step title="Activate the trigger">
    Navigate to **Runtime Settings** → **Manage Triggers** and activate the trigger to begin monitoring.
  </Step>
</Steps>

***

## Best practices

<CardGroup>
  <Card title="Use configuration parameters" icon="gear">
    Store Azure AD credentials (Tenant ID, Client ID, Client Secret) in configuration parameters for secure, environment-specific management.
  </Card>

  <Card title="Set appropriate validations" icon="shield-check">
    Configure file type, size, and count limits for Read scope to prevent processing of unwanted or oversized attachments.
  </Card>

  <Card title="Monitor failed triggers" icon="triangle-exclamation">
    Regularly review the Failed Triggers section to identify issues with email processing or connection problems.
  </Card>

  <Card title="Use least-privilege permissions" icon="lock">
    Grant only the minimum required MS Graph permissions for your scope. Use `Mail.Read` instead of `Mail.ReadWrite` if you only need read access.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection test fails" icon="circle-exclamation">
    Common causes:

    * **Invalid credentials**: Verify Tenant ID, Client ID, and Client Secret in Azure AD
    * **Missing permissions**: Ensure the app registration has the required MS Graph application permissions
    * **Permissions not consented**: Admin consent may be required for application permissions
    * **Expired client secret**: Generate a new client secret in Azure AD
  </Accordion>

  <Accordion title="Emails not triggering processes" icon="circle-exclamation">
    Check:

    1. Does the data source have **Read** or **Read & Send** scope?
    2. Is the trigger **Active** in Manage Triggers?
    3. Is the correct mailbox folder configured?
    4. Do incoming emails pass attachment validation rules?
    5. Review Failed Triggers for error details
  </Accordion>

  <Accordion title="Emails not sending" icon="circle-exclamation">
    Check:

    1. Does the data source have **Send** or **Read & Send** scope?
    2. Is the data source linked to a notification template?
    3. Is the notification template's **Email Server** set to **Predefined Email Connection**?
    4. Does the Azure AD app have `Mail.Send` permission?
    5. Review process instance logs for error details
  </Accordion>

  <Accordion title="Permission errors" icon="circle-exclamation">
    Required MS Graph **application permissions** by scope:

    | Scope | Required permission                                |
    | ----- | -------------------------------------------------- |
    | Read  | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
    | Send  | `Mail.Send` or `Mail.ReadWrite`                    |

    Ensure:

    * Permissions are set as **Application** (not Delegated)
    * **Admin consent** has been granted
    * The app registration is in the correct Azure AD tenant
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Email Trigger" icon="envelope-open-text" href="./email-trigger">
    Configure IMAP connections to trigger processes from incoming emails
  </Card>

  <Card title="Email Sender" icon="paper-plane" href="./email-sender">
    Configure SMTP connections to send emails from processes
  </Card>

  <Card title="Send Notification Action" icon="envelope" href="../../building-blocks/actions/send-notification-action">
    Send emails and reply to received emails from process nodes
  </Card>

  <Card title="Message Start Event" icon="play" href="../../building-blocks/node/message-events/message-catch-start-event">
    Configure message-based and email-based process triggers
  </Card>

  <Card title="Integration Designer" icon="puzzle-piece" href="./integration-designer">
    Learn about other data source types and workflow creation
  </Card>

  <Card title="Configuration Parameters" icon="sliders" href="../core-extensions/configuration-parameters">
    Use environment variables for flexible configurations
  </Card>
</CardGroup>


# Mock integrations
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/mock-integrations

If you need to test the business process flow but haven't completed all integrations, you can still do so by utilizing the mock integrations server included in the platform.

## Setup

To begin, configure the microservice's DB settings to use a Postgres DB. Then, deploy the mocked adapter microservice.

## Adding a new integration

Setting up a mocked integration requires only one step: adding a mock Kafka request and response.

You have two options for accomplishing this:

1. Add the information directly to the DB.
2. Use the provided [**API**](../../api/mocks/add-kafka-mock).

For each Kafka message exchange between the engine and the integration, you need to create a separate entry.

<Check>
  Check out the [**Add new exchange Kafka mock**](../../api/mocks/add-kafka-mock) API reference for more details.
</Check>

<Check>
  Check out the [**View all available Kafka exchanges**](../../api/mocks/view-kafka-exchanges) API reference for more details.
</Check>


# Observability with OpenTelemetry
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/open-telemetry

Monitor and analyze FlowX.AI platform performance using OpenTelemetry for distributed tracing, metrics, and logging.

## What is Observability?

Observability is the capacity to infer the internal state of a system by analyzing its external outputs. In software development, this entails understanding the internal workings of a system through its telemetry data, which comprises traces, metrics, and logs.

## What is Open Telemetry?

OpenTelemetry is an observability framework and toolkit for generating and managing telemetry data, including traces, metrics, and logs. It is vendor-agnostic and compatible with various observability backends like Jaeger and Prometheus. Unlike observability backends, OpenTelemetry focuses on the creation, collection, and export of telemetry data, leaving storage and visualization to other tools.

<Info>
  FlowX supports distributed tracing with OpenTelemetry.
</Info>

## How it works?

The monitoring and performance analysis system uses OpenTelemetry for comprehensive tracing and logging across our microservices architecture. By integrating with Grafana and other observability tools, we achieve detailed visibility into the lifecycle of requests, the performance of individual operations, and the interactions between different components of the system.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/otel_hla.drawio.png)

<Info>
  OTEL Collectors are designed in a vendor-agnostic way to receive, process and export telemetry data. For more information, see the [OTEL Collectors documentation](https://opentelemetry.io/docs/collector/).
</Info>

<Tip>
  Recommended OpenTelemetry Collector Processors: Follow the [**recommended processors**](https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor#recommended-processors).
</Tip>

## Prerequisites

### Microservices

* **Java agent**: Configuration and deployment of the OpenTelemetry Java agent enables automatic instrumentation with no code changes required.
* **Manual instrumentation** (optional): Custom code additions for creating custom spans and enriching traces with business context. This is an advanced use case — automatic instrumentation via the Java agent is sufficient for most deployments.
* **Performance impact assessment**: Evaluate the overhead of instrumentation in your environment before enabling in production.

### Kubernetes

* Use of a Kubernetes Operator for managing instrumentation and tracing configuration.

## Instrumentation

### Auto-instrumentation with Java agent

* **Works**: Automatically wraps methods at the application edges (HTTP calls, Kafka messages, DB calls), creating spans and adding default span attributes.
* **Configuration**: Configure the Java agent for auto-instrumentation.

### Manual instrumentation

* **Custom Spans**: These were created for methods important to the business flow and enriched with technical attributes such as `fx.type`, `fx.methodName`, `fx.processInstanceUuid`, and others.
* **Custom BUSINESS Spans**: Create spans for business events.

## Business logic metadata in logs and spans

Spans now include custom FlowX attributes (e.g., node names, action names, process names, instance UUIDs), which can be used for filtering and searching in traces.

Here is the full list of included custom FlowX span attributes:

### Custom span attributes

* fx.type - BUSINESS/TECHNICAL
* fx.methodName
* fx.parentProcessInstanceId
* fx.parentProcessInstanceUuid
* fx.processInstanceUuid
* fx.processName
* fx.processVersionId
* fx.tokenInstanceUuid
* fx.nodeName
* fx.nodeId
* fx.nodeUuid
* fx.boundaryEventId
* fx.nextNodeId
* fx.triggeredByBoundaryEventId
* fx.actionUuid
* fx.actionName
* fx.context
* fx.platform

### Custom business spans

* identified by the `fx.type = BUSINESS` attribute

### Detailed trace operations

Trace specific operations and measure request time across different layers/services.

* **Process Start**: Auto-instrumentation enabled for Spring Data to show time spent in repository methods. JDBC query instrumentation can be added.
* **Token Creation and Advancing**: Custom tracing added.
* **Action Execution and Subprocess Start**: Custom tracing added.

## Troubleshooting scenarios and common usages

### Scenario examples

* **Process Trace**: Analyze DB vs cache times, token advancement, node actions.
* **Parallel Gateway**: Trace split tokens.
* **DB Query Time**: Enable JDBC query tracing.
* **Endpoint Data Issues**: Check traces for Redis or DB source.
* **Token Stuck**: Filter by node name and process UUID.
* **Action Execution**: Trace action names for stuck tokens.
* **Subprocess Failures**: Analyze subprocess start and failures.
* **Latency Analysis**: Identify latencies in automatic actions.
* **Boundary Events**: Ensure Kafka schedule messages are sent and received correctly.
* **External Service Tracking**: Trace between process engine and external plugins.

### Business operation analysis

* **Long Running Operations**: Use Uptrace for identifying slow operations.
* **Failed Requests**: Filter traces by error status.

### Visualization of Traces

<Tip>
  We recommend to use Grafana, but any observability platform compatible with OpenTelemetry standards can be used.
</Tip>

Grafana integrates with tracing backends such as Tempo (for tracing) and Loki (for logging), allowing us to visualize the entire lifecycle of a request. This includes detailed views of spans, which are the basic units of work in a trace. By using Grafana, we can:

* **View Trace Trees**: Grafana provides an intuitive UI for viewing the hierarchy and relationships between spans, making it easier to understand the flow of a request through the system.
* **Filter and Search**: Use Grafana to filter and search spans based on custom attributes like `fx.processInstanceUuid`, `fx.nodeName`, `fx.actionName`, and others. This helps in pinpointing specific operations or issues within a trace.
* **Error Analysis**: Identify spans with errors and visualize the stack trace or error message, aiding in quick troubleshooting.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/custom_spans.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/custom_spans1.png)
</Frame>

Resources:

<Card title="OpenTelemetry Docs" href="https://opentelemetry.io/docs/" icon="link" />


# Oracle Database
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/oracle-database

Connect to Oracle databases as a data source in FlowX workflows and run SQL queries against them.

## Overview

Oracle Database is a relational data source type that lets you connect FlowX workflows to **Oracle databases that your organization manages independently**. You configure a connection, save named SQL queries against the schema, and call those queries from workflows.

<CardGroup>
  <Card title="Connect to your Oracle instance" icon="database">
    Connect via Service Name or SID, with an optional SSL toggle
  </Card>

  <Card title="Schema-aware SQL editor" icon="code">
    Monaco editor with SQL syntax highlighting, schema-aware autocomplete, and a side panel that lists tables, columns, primary keys, and foreign keys
  </Card>

  <Card title="Test before you ship" icon="flask">
    Run any saved query with sample parameters and inspect the response: table view for SELECT, affected-row count for INSERT / UPDATE / DELETE
  </Card>

  <Card title="Reusable in workflows" icon="diagram-project">
    Reference Oracle queries from the Database Operation node alongside other data sources
  </Card>
</CardGroup>

***

## Prerequisites

* An Oracle Database 21c or 23ai instance accessible from your FlowX deployment
* A database user with the privileges your queries require (typically `SELECT`, `INSERT`, `UPDATE`, `DELETE` on the target schema, plus `SELECT` on data dictionary views for schema discovery)
* Network connectivity between the `nosql-db-runner` service and the Oracle instance
* For SSL connections: appropriate certificates configured on the Oracle instance and trusted by the FlowX deployment

***

## Creating an Oracle Database data source

<Frame>
  ![Oracle Database data source settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/oracle_data_source_settings.png)
</Frame>

<Steps>
  <Step title="Open Data Sources">
    Navigate to **Integration Designer** → **Data Sources** in your project.
  </Step>

  <Step title="Add a new data source">
    Click the **+** button to open the **Add Data Source** dialog. In the **Databases** category, select **Oracle Database**.
  </Step>

  <Step title="Configure the connection">
    Fill in the connection fields:

    | Field                   | Description                                               |
    | ----------------------- | --------------------------------------------------------- |
    | **Host**                | Oracle server hostname or IP                              |
    | **Port**                | Oracle listener port (default `1521`)                     |
    | **Database Name / SID** | The service name or SID, depending on the connection type |
    | **Schema Name**         | Optional. The schema to use for queries and discovery     |
    | **SSL Enabled**         | Toggle SSL on or off for the connection                   |
    | **Connection Type**     | **Service Name** or **SID**                               |
    | **Username**            | Database username                                         |
    | **Password**            | Database password                                         |

    Each field accepts configuration parameters for environment-specific values.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection and Rescan** to verify connectivity and refresh the schema cache.

    <Note>
      The data source is created even if the connection test fails, so you can save partial configuration and resolve connectivity later. Return to the **Settings** tab and click **Test Connection and Rescan** once the issue is fixed.
    </Note>
  </Step>

  <Step title="Save">
    Click **Save** to create the data source.
  </Step>
</Steps>

***

## Queries

Each Oracle Database data source holds a list of named SQL queries. A query is a single parameterized SQL statement that you can call from a workflow.

### SQL editor

Open the **Queries** tab on the data source, then click **New query** to open the editor:

* **Query area**: Monaco editor with SQL syntax highlighting and schema-aware autocomplete. Use Oracle-native bind variables (`:paramName`); they're auto-detected from the query text and surfaced in the parameters panel.
* **Parameters panel** (left): declare each bind parameter with a type. Supported types are `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, and `CURRENCY`.
* **Schema browser** (right): pick a table from the dropdown to inspect its columns. Primary-key and foreign-key badges appear next to column names. Hover a foreign-key badge to see the referenced table and column.

<Info>
  The Monaco editor ships a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel. Hover and bracket matching match the rest of the FlowX code editors.
</Info>

### Testing a query

Click **Test query** to open the test modal:

* **Parameters**: supply values for declared bind parameters.
* **Query and tables**: view the SQL and the resolved schema context.
* **Response**: for `SELECT`, results render as both a table and JSON, with `totalCount` and `executionTimeMs`. For `INSERT` / `UPDATE` / `DELETE`, the response is `affectedRows`. Errors include the Oracle `sqlState` and message (for example, `ORA-00942: table or view does not exist`).

The modal warns before discarding unsaved changes.

***

## Stored procedures, functions, and views

Beyond plain `SELECT` and DML statements, Oracle Database queries can also target **views**, **functions**, and **stored procedures**. The schema browser discovers each as a distinct entity type, so you can reference them the same way you reference tables.

| Entity                | How to call it                                                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Views**             | Query like any table: `SELECT * FROM V_MONTHLY_REVENUE WHERE month = :m`. Non-updatable views are read-only; an `UPDATE` against one is rejected.                                                      |
| **Scalar functions**  | Wrap in a `SELECT` against `dual`: `SELECT FN_CALCULATE_VAT(:amount, :country) AS vat FROM dual`.                                                                                                      |
| **Table functions**   | Wrap in `TABLE(...)`: `SELECT * FROM TABLE(FN_GET_ACTIVE_ORDERS(:customer_id))`.                                                                                                                       |
| **Stored procedures** | Call inside an anonymous PL/SQL block: `BEGIN SP_CREATE_INVOICE(:order_id, :issue_date, :invoice_id, :invoice_pdf); END;`. Output parameters and `REF CURSOR` results are returned as described below. |

<Note>
  A function that has `OUT` (or `IN OUT`) parameters cannot be called from a `SELECT` — only from a PL/SQL block. To use a function inside a `SELECT`, it must take `IN` parameters only and return its value via `RETURN`.
</Note>

### Returning data from stored procedures

A stored procedure returns its results through **output parameters**. Because output parameters are not part of the SQL result set by default, you must declare them explicitly so the engine knows what to read back.

Declare the output parameters in a `-- OUT:` comment at the top of the script, before the `BEGIN` block. List each parameter as `<parameter_name> <TYPE>`, separated by commas:

```sql theme={"system"}
-- OUT: p_count NUMBER, p_status VARCHAR2
BEGIN
  my_package.my_procedure(p_count => :p_count, p_status => :p_status);
END;
```

Rules:

* The declaration must come at the top of the script, before the `BEGIN` block.
* `<parameter_name>` must exactly match the corresponding output parameter in the procedure's signature (`p_count` here maps to the procedure's `p_count` OUT parameter).
* `<TYPE>` must match the parameter's declared type in the procedure — for example `NUMBER`, `VARCHAR2`, or `DATE`.

<Warning>
  If an output parameter is not declared this way, the script runs but no data is returned for it.
</Warning>

<Tip>
  This comment-based declaration is the current convention for surfacing procedure output. Procedure output parameters and Oracle `REF CURSOR` results are unwrapped into the response result set, so the calling workflow can map them to variables like any other query response.
</Tip>

***

## Using in workflows

Oracle queries are called from the existing **Database Operation** node in workflows.

<Steps>
  <Step title="Add a Database Operation node">
    On the workflow canvas, drag a **Database Operation** node onto the workspace.
  </Step>

  <Step title="Select the data source and query">
    In the node configuration panel, pick the Oracle data source. The query picker then lists only the queries saved on that data source.
  </Step>

  <Step title="Map parameters">
    Map workflow inputs to the query's bind parameters. Map the response (rows or `affectedRows`) to a workflow variable.
  </Step>
</Steps>

<Tip>
  Scoping the picker to the selected data source keeps Oracle queries and MongoDB operations separate, even when both data source types exist in the same project.
</Tip>

***

## Deployment

No new microservices are required. Oracle Database queries run inside the existing **`nosql-db-runner`** service, which bundles the Oracle JDBC driver. Each Oracle data source uses its own HikariCP connection pool.

### Configuration defaults

The following defaults apply to all Oracle data sources and can be tuned via environment variables on the `nosql-db-runner` service:

| Environment Variable                            | Description                                | Default |
| ----------------------------------------------- | ------------------------------------------ | ------- |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES`      | Maximum cached JDBC connection pools       | `100`   |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL`              | Time-to-live for cached connection pools   | `1d`    |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE`              | Maximum HikariCP pool size per data source | `5`     |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout                    | `10`    |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT`                  | Default row cap on `SELECT` responses      | `1000`  |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS`      | Query execution timeout                    | `30`    |

### Per-data-source advanced settings

Each Oracle data source can override the global defaults from its **Advanced settings** panel in the Integration Designer. Fields left empty inherit the global value:

| Property                       | Description                                                      |
| ------------------------------ | ---------------------------------------------------------------- |
| **connectionTimeoutMs**        | Maximum time to wait for a JDBC connection from the pool         |
| **idleTimeoutMs**              | Time an idle connection may sit in the pool before being retired |
| **maxLifetimeMs**              | Maximum lifetime of a pooled connection                          |
| **maintenanceFrequencyMs**     | Interval between pool housekeeping runs                          |
| **queryTimeoutMs**             | Per-query execution timeout for this data source                 |
| **keepAlive**                  | Keep-alive probing for pooled connections                        |
| **preparedStatementCacheSize** | Number of prepared statements cached per connection              |
| **validationQuery**            | Query used to validate connections before use                    |

Ensure the `nosql-db-runner` service has network access to your Oracle instance. If Oracle is behind a firewall, configure the appropriate network rules.

***

## Related resources

<CardGroup>
  <Card title="FlowX Database" icon="database" href="./flowx-database">
    Managed MongoDB data storage within FlowX
  </Card>

  <Card title="Unmanaged MongoDB" icon="leaf" href="./unmanaged-mongodb">
    Connect to externally managed MongoDB instances
  </Card>

  <Card title="Integration Designer" icon="diagram-project" href="./integration-designer">
    Overview of all data source types and workflow building
  </Card>

  <Card title="NoSQL DB Runner setup" icon="gear" href="/5.9/setup-guides/nosql-db-runner">
    Deployment configuration for the database runner service
  </Card>
</CardGroup>


# Proxy connections
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/proxy-connections

Create and manage reusable proxy connections to route data source traffic through HTTP or HTTPS proxy servers.

## Overview

Proxy connections let you route data source traffic through an intermediary proxy server. Instead of configuring proxy settings on each data source individually, you create reusable proxy connection resources in Integration Designer and attach them to one or more data sources.

This is useful in environments where outbound traffic must pass through a corporate proxy, or when you need to route API calls through a specific gateway for security or compliance reasons.

***

## Key features

<CardGroup>
  <Card title="HTTP and HTTPS" icon="lock">
    Support for both HTTP and HTTPS proxy protocols
  </Card>

  <Card title="Basic authentication" icon="key">
    Optional user and password authentication for proxy servers that require credentials
  </Card>

  <Card title="Test connectivity" icon="check">
    Validate proxy configuration before saving with the built-in test function
  </Card>

  <Card title="Reusable across data sources" icon="arrows-rotate">
    Create a proxy once and attach it to multiple RESTful System data sources
  </Card>
</CardGroup>

***

## Managing proxy connections

Proxy connections are managed from the **Proxy Connections** section in Integration Designer.

To access the proxy list:

<Steps>
  <Step title="Open your project">
    Open **FlowX Designer** and navigate to your project.
  </Step>

  <Step title="Expand Integrations">
    In the left sidebar, expand **Integrations**.
  </Step>

  <Step title="Open Proxy Connections">
    Click **Proxy Connections**.
  </Step>
</Steps>

<Frame>
  ![Proxy Connections list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_list.png)
</Frame>

The list displays all configured proxy connections with the following information:

| Column          | Description                                 |
| --------------- | ------------------------------------------- |
| **Name**        | The proxy connection name                   |
| **Description** | Optional description of the proxy's purpose |
| **Type**        | HTTP or HTTPS                               |
| **Edited by**   | User who last modified the proxy            |
| **Edited at**   | Date and time of last modification          |

***

## Adding a proxy connection

<Steps>
  <Step title="Open the proxy creation form">
    From the **Proxy Connections** list, click the **+** button at the top of the page.
  </Step>

  <Step title="Configure basic information">
    <Frame>
      ![Add Proxy Connection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_add.png)
    </Frame>

    Fill in the following fields:

    | Field           | Required | Description                                                                                |
    | --------------- | -------- | ------------------------------------------------------------------------------------------ |
    | **Name**        | Yes      | A unique name for the proxy connection                                                     |
    | **Description** | No       | Purpose or context for this proxy                                                          |
    | **Proxy Type**  | Yes      | Select **HTTP** or **HTTPS**                                                               |
    | **Proxy Host**  | Yes      | The proxy server hostname or IP address. Supports `${param}` for configuration parameters. |
    | **Proxy Port**  | Yes      | The proxy server port number. Supports `${param}` for configuration parameters.            |
  </Step>

  <Step title="Set auth type">
    Select an **Auth Type** from the dropdown:

    <Tabs>
      <Tab title="NO_AUTH">
        No authentication required. The proxy accepts connections without credentials.
      </Tab>

      <Tab title="BASIC">
        Username and password authentication for the proxy server.

        **Required fields:**

        <ParamField type="string">
          The user for proxy authentication.
        </ParamField>

        <ParamField type="string">
          The password for proxy authentication. Stored securely.
        </ParamField>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test the proxy connection">
    Click **Test Connection** to validate the configuration. The system attempts to connect through the proxy and reports success or failure.

    <Check>
      If the test succeeds, the proxy is ready to use. If it fails, verify the host, port, and credentials.
    </Check>
  </Step>

  <Step title="Create the proxy">
    Click **Create** to save the proxy connection. It is now available for use with data sources.
  </Step>
</Steps>

***

## Using proxies with data sources

Proxy connections can be attached to **RESTful System** data sources. When a proxy is attached, all API calls made through that data source are routed through the proxy server.

### Attaching a proxy to a data source

<Steps>
  <Step title="Open a RESTful System data source">
    Navigate to the data source configuration in Integration Designer. This works for both new and existing RESTful System data sources.
  </Step>

  <Step title="Turn on proxy routing">
    Toggle **Connect through Proxy** to **ON**. A new dropdown field appears.
  </Step>

  <Step title="Select a proxy connection">
    Choose a proxy from the **Select Proxy Connection** dropdown. The list shows all available proxy connections in the current project.

    If no proxies exist, the dropdown shows a **Create** option that takes you to the proxy creation form.
  </Step>

  <Step title="Save the data source">
    Save the data source configuration. All subsequent API calls through this data source will be routed through the selected proxy.
  </Step>
</Steps>

<Warning>
  If you delete a proxy connection that is in use by a data source, the data source does **not** automatically switch back to a direct connection. You must manually update the data source configuration.
</Warning>

***

## Example: route a CRM integration through a corporate proxy

In this scenario, your organization requires all outbound API traffic to pass through a corporate proxy server before reaching external services. You have a RESTful System data source that connects to a CRM API and need to route its traffic through the proxy.

<Steps>
  <Step title="Create the proxy connection">
    Go to **Integrations** → **Proxy Connections** and click **+**. Configure:

    | Field           | Value                                                |
    | --------------- | ---------------------------------------------------- |
    | **Name**        | `Corporate Proxy`                                    |
    | **Description** | `Routes traffic through the corporate proxy gateway` |
    | **Proxy Type**  | `HTTPS`                                              |
    | **Proxy Host**  | `proxy.corp.example.com`                             |
    | **Proxy Port**  | `8443`                                               |
    | **Auth Type**   | `BASIC`                                              |
    | **User**        | `svc-flowx`                                          |
    | **Password**    | `••••••••`                                           |

    Click **Test Connection** to verify, then click **Create**.

    <Frame>
      ![Corporate Proxy example configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
    </Frame>

    <Tip>
      Use configuration parameters for values that change across environments, for example `${corp.proxy.host}` for the host and `${corp.proxy.port}` for the port. This way the same project works in dev, staging, and production with different proxy servers.
    </Tip>
  </Step>

  <Step title="Attach the proxy to a data source">
    Go to **Integrations** → **Data Sources** and open your CRM data source (RESTful System type).

    Toggle **Connect through Proxy** to **ON** and select **Corporate Proxy** from the dropdown. Save the data source.
  </Step>

  <Step title="Verify in runtime">
    Run a workflow that uses the CRM data source. In the runtime console, the cURL preview now reflects the proxy:

    ```bash theme={"system"}
    curl --proxy https://proxy.corp.example.com:8443 --proxy-user svc-flowx:******** https://crm.example.com/api/v2/contacts
    ```
  </Step>
</Steps>

***

## Proxy in cURL commands

When a proxy is active on a RESTful System data source, the cURL command preview in the runtime console reflects the proxy configuration.

**Without proxy:**

```bash theme={"system"}
curl https://api.example.com/data
```

**With proxy (no auth):**

```bash theme={"system"}
curl --proxy http://proxy-host:8080 https://api.example.com/data
```

**With proxy (basic auth):**

```bash theme={"system"}
curl --proxy http://proxy-host:8080 --proxy-user user:password https://api.example.com/data
```

**With HTTPS proxy:**

```bash theme={"system"}
curl --proxy https://proxy-host:8443 https://api.example.com/data
```

***

## Configuration reference

| Property        | Type                 | Required   | Description                                              |
| --------------- | -------------------- | ---------- | -------------------------------------------------------- |
| **Name**        | `string`             | Yes        | Unique name for the proxy connection                     |
| **Description** | `string`             | No         | Optional description                                     |
| **Proxy Type**  | `HTTP` \| `HTTPS`    | Yes        | The proxy protocol                                       |
| **Proxy Host**  | `string`             | Yes        | Proxy server hostname or IP. Supports `${param}` syntax. |
| **Proxy Port**  | `number`             | Yes        | Proxy server port. Supports `${param}` syntax.           |
| **Auth Type**   | `NO_AUTH` \| `BASIC` | Yes        | Authentication method                                    |
| **User**        | `string`             | When Basic | Proxy auth user                                          |
| **Password**    | `string`             | When Basic | Proxy auth password                                      |

***

## Limitations

The following proxy types and authentication methods are not supported in this release:

| Not supported           | Notes                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| SOCKS4 / SOCKS5         | Only HTTP and HTTPS proxy types are available                                                                        |
| PAC URL                 | Proxy auto-configuration URLs are not supported                                                                      |
| Client credentials auth | Only No Auth and Basic Authentication are available                                                                  |
| mTLS                    | Mutual TLS authentication for proxy servers is not supported                                                         |
| MCP Server data sources | MCP connections use their own [inline proxy configuration](./mcp-integration/mcp-integration-overview#proxy-support) |

***

## Related resources

<CardGroup>
  <Card title="Integration Designer" icon="link" href="./integration-designer">
    Data sources and workflow integrations
  </Card>

  <Card title="MCP Integration" icon="robot" href="./mcp-integration/mcp-integration-overview">
    MCP server connections with separate proxy support
  </Card>
</CardGroup>


# Unmanaged MongoDB
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb

Connect to externally managed MongoDB instances as a data source in FlowX workflows.

## Overview

Unmanaged MongoDB is a data source type that lets you connect FlowX workflows to **external MongoDB databases that your organization manages independently**. Unlike the built-in [FlowX Database](./flowx-database) — which provisions and manages MongoDB collections automatically — Unmanaged MongoDB connects to existing databases and collections you control.

<CardGroup>
  <Card title="Use your infrastructure" icon="server">
    Connect to MongoDB instances you already manage, including Atlas, self-hosted, or cloud-managed deployments
  </Card>

  <Card title="Same operations" icon="arrows-rotate">
    Use the same CRUD operations (find, insert, update, delete) as FlowX Database
  </Card>

  <Card title="Connection discovery" icon="magnifying-glass">
    Browse available databases and collections directly from the Designer after connecting
  </Card>

  <Card title="Connection pooling" icon="gauge-high">
    Configure pool size, idle timeouts, and maintenance frequency per data source
  </Card>
</CardGroup>

***

## Managed vs unmanaged MongoDB

| Aspect                  | FlowX Database (managed)                          | Unmanaged MongoDB                                                                |
| ----------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Collection creation** | Automatic — FlowX creates and manages collections | Manual — you provide an existing collection                                      |
| **Schema management**   | Defined in FlowX Designer                         | Optional — you manage schemas externally                                         |
| **Index management**    | CRUD via Designer UI                              | You manage indexes externally                                                    |
| **Connection**          | Internal, handled by FlowX                        | You provide a connection URI                                                     |
| **Auth**                | Internal                                          | Username/password (SCRAM-SHA-256), or credentials embedded in the connection URI |
| **Use case**            | Data sharing between FlowX processes              | Integrate with existing MongoDB infrastructure                                   |

<Tip>
  Use **FlowX Database** when you need FlowX to manage the full lifecycle of your data. Use **Unmanaged MongoDB** when you need to read from or write to databases that exist outside FlowX.
</Tip>

<Note>
  Both [FlowX Database](./flowx-database) (managed) and Unmanaged MongoDB are served by the same **nosql-db-runner** service. Managed collections are stored in nosql-db-runner's own MongoDB database, while an Unmanaged MongoDB data source opens a separate, isolated connection to the external instance you specify — it never touches nosql-db-runner's internal database. Point it at infrastructure you own and manage.
</Note>

***

## Prerequisites

* A MongoDB 6.0+ instance accessible from your FlowX deployment
* An existing database and collection on the target instance
* A MongoDB user with appropriate permissions (read, write, or both)
* Network connectivity between FlowX services and the MongoDB instance
* For TLS/SSL connections: appropriate certificates configured on the MongoDB instance

***

## Creating an Unmanaged MongoDB data source

<Frame>
  ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
</Frame>

<Steps>
  <Step title="Open Data Sources">
    Navigate to **Integrations** → **Data Sources** in your project.
  </Step>

  <Step title="Create a new data source">
    Click **New Data Source** and select **Unmanaged MongoDB** as the type.
  </Step>

  <Step title="Configure the connection">
    Enter the MongoDB connection URI:

    ```
    mongodb+srv://username:password@cluster.example.net
    ```

    Or standard format:

    ```
    mongodb://username:password@host:27017
    ```
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify connectivity and credentials.
  </Step>

  <Step title="Select database and collection">
    After a successful connection test, browse available databases and select the target database. Then browse and select the target collection.
  </Step>

  <Step title="Configure authorization (optional)">
    In the **Authorization** tab, configure authentication if not embedded in the connection URI.
  </Step>

  <Step title="Save">
    Click **Save** to create the data source.
  </Step>
</Steps>

<Warning>
  The target collection must already exist on the MongoDB instance. FlowX does not create collections on unmanaged databases.
</Warning>

***

## Connection pool configuration

Each Unmanaged MongoDB data source has its own connection pool. You can tune pool settings in the data source **Settings** tab:

| Setting                   | Description                                             | Default             |
| ------------------------- | ------------------------------------------------------- | ------------------- |
| **Min pool size**         | Minimum number of connections maintained                | `0`                 |
| **Max pool size**         | Maximum number of concurrent connections                | `100`               |
| **Max idle time**         | How long an idle connection stays open                  | `60000` ms (1 min)  |
| **Max lifetime**          | Maximum lifetime of a connection                        | `0` (unlimited)     |
| **Wait queue timeout**    | How long a request waits for an available connection    | `120000` ms (2 min) |
| **Maintenance frequency** | How often the pool checks for idle connections to close | `60000` ms (1 min)  |

<Tip>
  For production workloads, set **Min pool size** to match your baseline concurrent usage to avoid connection warm-up latency.
</Tip>

***

## Operations

Unmanaged MongoDB supports the same operations as [FlowX Database](./flowx-database):

| Operation    | Description                                   |
| ------------ | --------------------------------------------- |
| `find`       | Retrieve multiple documents based on criteria |
| `findOne`    | Retrieve a single document                    |
| `insertOne`  | Add a single document                         |
| `insertMany` | Add multiple documents at once                |
| `updateOne`  | Modify a single document                      |
| `updateMany` | Modify multiple documents at once             |
| `deleteOne`  | Remove a single document                      |
| `deleteMany` | Remove multiple documents at once             |

Operations are configured the same way as FlowX Database operations — with filters, projections, sorting, and parameter substitution using `${paramName}` syntax. You can test operations directly in the Designer before using them in workflows.

The **Documents** tab on the data source page lets you browse documents in the collection with pagination, filtering, and sorting.

For details on configuring each operation, see the [FlowX Database operations documentation](./flowx-database#mongodb-operations-supported).

***

## Using in workflows

Unmanaged MongoDB data sources are used in workflows the same way as other data sources:

<Steps>
  <Step title="Create operations">
    Define operations on the data source (find, insert, update, delete).
  </Step>

  <Step title="Add a Data Source node">
    Add a **Data Source** node to your workflow.
  </Step>

  <Step title="Select the data source">
    Select the Unmanaged MongoDB data source and operation.
  </Step>

  <Step title="Map parameters">
    Map input/output parameters in the data mapper.
  </Step>
</Steps>

***

## Deployment

No additional microservices are required. Unmanaged MongoDB uses the existing **nosql-db-runner** service to execute operations against your external MongoDB instance.

Ensure the `nosql-db-runner` service has network access to your MongoDB instance. If your MongoDB is behind a firewall, configure the appropriate network rules.

***

## Related resources

<CardGroup>
  <Card title="FlowX Database" icon="database" href="./flowx-database">
    Managed MongoDB data storage within FlowX
  </Card>

  <Card title="Integration Designer" icon="diagram-project" href="./integration-designer">
    Overview of all data source types and workflow building
  </Card>

  <Card title="NoSQL DB Runner setup" icon="gear" href="/5.9/setup-guides/nosql-db-runner">
    Deployment configuration for the database runner service
  </Card>
</CardGroup>


# Workflow data model
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/workflow-data-models

Define structured data models at the workflow level with input and output parameters, enabling consistent data lineage and structured integration between processes and Integration Designer workflows.

<Tip>
  **Workflow data models** define input and output parameters for **Start Nodes** and **End Nodes**:

  * **Input parameters**: Define the data structure that enters the workflow through the Start Node. The input parameters automatically pre-fill the Start Node when you open the workflow diagram or test the workflow at runtime.
  * **Output parameters**: Define the data structure returned by End Nodes when the workflow completes.

  When a workflow is integrated into another resource (for example, a process), these parameters define how data is processed between the two components:

  * **Input mapping** (Start Integration Workflow Action): Maps data from the process to the workflow's input parameters when starting the workflow.
  * **Output mapping** (Receive Message Task): Maps data returned from the workflow back to the process variables.
</Tip>

## Overview

<Frame title="Workflow data model">
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
</Frame>

Workflow data models bring the same structured data management capabilities available in Process Definitions to Integration Designer workflows. By defining data models at the workflow level, you ensure consistent data lineage across your integration architecture, making workflows more reusable, testable, and maintainable.

<CardGroup>
  <Card title="Structured Data Management" icon="database">
    Define entities, attributes, and custom data types at the workflow level, similar to Process Data Models
  </Card>

  <Card title="Input/Output Parameters" icon="arrows-left-right">
    Specify which data enters and exits your workflow with automatic parameter management
  </Card>

  <Card title="Process Integration" icon="link">
    Map data bidirectionally between processes and workflows using data mappers
  </Card>

  <Card title="Type Safety & Validation" icon="shield-check">
    Define data types and validation rules to ensure runtime data integrity
  </Card>
</CardGroup>

***

## Key concepts

### Workflow data model

A Workflow Data Model defines the structure of data used throughout a workflow's execution. It consists of:

* **Entities**: Logical groupings of related data (for example, Customer, Order, Payment)
* **Attributes**: Individual data fields with types and constraints
* **Input Parameters**: Subset of the data model defining workflow input parameters
* **Output Parameters**: Subset of the data model defining workflow output parameters

### Workflow

Workflow parameters are defined in the data model that define which data is passed as input or returned as output:

* **Input Parameters**: Automatically pre-fills the Start Node with structured data when you open the workflow diagram tab or test the workflow at runtime
* **Output Parameters**: Defines the data structure returned by End Nodes. Currently, output parameters work as-is (you can manually configure them), but automatic pre-filling from output parameters is planned for future releases

### Node name uniqueness

<Warning>
  Node names within a workflow must be unique to ensure clear data lineage and avoid ambiguity when mapping data.
</Warning>

When you rename nodes, the system validates uniqueness. If a duplicate name exists, an index is automatically appended (for example, `Transform`, `Transform_2`, `Transform_3`).

***

## Creating a workflow data model

<Steps>
  <Step title="Navigate to Workflow Settings">
    Open your workflow in Integration Designer and navigate to the **Data Model** tab in workflow settings.

    <Frame>
      ![Workflow Data Model Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_dm.png)
    </Frame>
  </Step>

  <Step title="Define Entities">
    Create entities to represent the logical data structures in your workflow:

    * Click **Create Attribute**
    * Enter an entity name (e.g., `Customer`, `Order`)
    * Add a description for documentation
  </Step>

  <Step title="Add Attributes">
    For details on adding and configuring attributes for your data model—including data types, required fields, validation, and advanced options—see the [**Data Model**](../../building-blocks/process/data-model) documentation.
  </Step>

  <Step title="Configure Input Parameters">
    Define which data will be passed as input to your workflow:

    * Navigate to **Input/Output Parameters** tab
    * Click **Define parameters** in the Input section
    * Select attributes from your data model to include
    * Mark required parameters

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Process%20-%20Input%20Params.png)
    </Frame>

    <Info>
      Input parameters data automatically pre-fills the Start Node when you open the workflow diagram or test at runtime.
    </Info>
  </Step>

  <Step title="Configure Output Parameters">
    Define which data will be returned when your workflow completes:

    * In the **Input/Output Parameters** tab, scroll to the Output section
    * Click **Define parameters** in the Output section
    * Select attributes from your data model to include as outputs
    * These parameters define the data structure returned by End Nodes

    <Info>
      Output parameters are used when mapping workflow results back to the calling process via the Receive Message Task.
    </Info>
  </Step>

  <Step title="Save and Test">
    Save your data model and test the workflow to verify input and output parameter mapping works correctly.
  </Step>
</Steps>

***

## Input parameter management

### Automatic start node pre-filling

When you define input parameters, the Workflow Start Node is automatically populated with the structured data:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/input_parameters.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prefill_start_node.png)
</Frame>

<Warning>
  **Important**: If you manually modify the JSON structure in the Start Node, your changes will be lost when you refresh the workflow diagram or reopen the workflow. The Start Node is automatically populated from the input parameters definition, so any manual edits are overwritten.

  To change the input structure, update the input parameters definition in the **Input/Output Parameters** tab instead of editing the Start Node JSON directly.
</Warning>

### Empty input parameters behavior

If no input parameters are defined for a workflow, the Start Node contains an empty object (`{}`). The input parameters are optional, but defining it provides better structure and type safety for your workflow inputs.

### Benefits of input parameters

<CardGroup>
  <Card title="No Manual Editing" icon="wand-magic-sparkles">
    Input parameters automatically pre-fill the Start Node - no JSON editing needed
  </Card>

  <Card title="Type Safety" icon="shield-check">
    Data types are enforced at the workflow level, preventing runtime errors
  </Card>

  <Card title="Clear Contracts" icon="file-contract">
    Input parameters document exactly what data the workflow expects
  </Card>

  <Card title="Easier Testing" icon="flask">
    Test workflows with structured input data based on the data model
  </Card>
</CardGroup>

***

## Integration with processes

### Process to workflow data mapping

Use data mappers to pass data from processes to workflows. The data mapper configuration in the **Start Integration Workflow** action maps process data to workflow input parameters, independent of the workflow's input parameters definition.

<Info>
  The workflow's input parameters are used for:

  * Pre-filling the Start Node when designing/testing workflows
  * Documenting the expected input structure

  When invoking workflows from processes via **Start Integration Workflow** action, data mappers handle the actual data mapping at runtime.
</Info>

<Steps>
  <Step title="Add Start Integration Workflow Action">
    In your process definition, add a **Start Integration Workflow** action to the node where you want to invoke the workflow. Choose the workflow you want to invoke from the dropdown.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/test_wk_dm.png)
    </Frame>
  </Step>

  <Step title="Configure Input Mapping">
    Access **Input Mapping** tab to configure the input mapping.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_input_mapping.png)
    </Frame>

    Map process data to workflow input parameters using the data mapper:

    ```json theme={"system"}
    {
      "customerId": "${application.customer.id}",
      "accountNumber": "${application.account.number}",
      "amount": "${application.transaction.amount}"
    }
    ```

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_input_mapping1.png)
    </Frame>

    <Check>
      The keys on the left should match your workflow's input parameters for consistency, though the data mapper operates independently.
    </Check>
  </Step>

  <Step title="Add Receive Message Task">
    Add a **Receive Message Task** node to capture workflow output when the workflow completes.

    Add a **Data Stream** by going to the **Node Config -> Integration Output -> Data Streams** tab and clicking **Add Data Stream**.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_output_mapping.png)
    </Frame>
  </Step>

  <Step title="Configure Output Mapping">
    Create a data mapper on the Receive Message Task to map workflow outputs back to process data:

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_output_mapping1.png)
    </Frame>
  </Step>
</Steps>

<Tip>
  When you use User Tasks, the input and output mapping are both available in the User Task node configuration at Node Config -> Integration Input/Output -> Data Streams.
</Tip>

### Example: User search workflow

This example demonstrates a workflow that searches for a user in the FlowX database using a username and returns the user's available information.

#### Workflow data model configuration

Configure your workflow data model with the following parameters:

**Input Parameter:**

* `username` (String, required) - The user's name to search for

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex.png)
</Frame>

**Output Parameter:**

* `user` (Object) - The user object containing all available user information

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex1.png)
</Frame>

#### Process setup

The process includes:

1. **User Task**: Contains an input field where users enter the username to search

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex2.png)
</Frame>

2. **Search Button**: Triggers the **Start Integration Workflow** action

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex3.png)
</Frame>

3. **Results Container**: Configured with conditional visibility to display only when results are returned

```text Example theme={"system"}
**User found:**
Name: ${user.name}
Account ID: ${user.account_id}
Active user: ${user.is_active}
```

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex4.png)
</Frame>

#### Mapping configuration

The **Start Integration Workflow** action requires two mapping configurations:

**Input Mapping (Process → Workflow):**

Maps the username from the main process to the workflow's expected input variable:

```json theme={"system"}
{
  "username": "${user.name}"
}
```

**Output Mapping (Workflow → Process):**

To configure output mapping:

1. Add a **data stream** for the workflow on the Receive Message Task
2. Define the user object as the output variable needed by the main process
3. Link the workflow's returned variables to the process variables

```json theme={"system"}
{
  "user": "${user}" //entire user object is returned
}
```

<Info>
  The output mapping displays all available end nodes from the workflow. Select the appropriate end node that returns the user data.
</Info>

### User database

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex6.png)
</Frame>

<Info>
  The user database is a simple database with a single user object.
</Info>

#### Workflow diagram

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex5.png)
</Frame>

<Info>
  You can see the start workflow node is pre-filled with the input parameter.
</Info>

#### Execution results

When the process runs and the search action executes:

**Workflow Input:**

```json theme={"system"}
{
  "username": "Joshua Helk"
}
```

**Workflow Output:**

```json theme={"system"}
{
  "user": {
    "_id": "6936ceb5c72d63c5585b93e7",
    "name": "Joshua Helk",
    "account_id": "dsa76d09ashu0231",
    "creation_date": "date",
    "is_active": true
  }
}
```

After workflow completion, all output information is available in the process variables of the main process, and the results container displays the user information.

***

## Best practices

### Data model structure

<CardGroup>
  <Card title="Use logical entities" icon="sitemap">
    Group related attributes into meaningful entities that represent domain concepts
  </Card>

  <Card title="Consistent naming" icon="text">
    Use camelCase for attributes and PascalCase for entities consistently
  </Card>

  <Card title="Reuse existing data types" icon="layer-group">
    Reuse existing data types for bulk mapping to simplify data model creation and ensure consistency
  </Card>

  <Card title="Document everything" icon="book">
    Add descriptions to entities and attributes for better team understanding
  </Card>

  <Card title="Keep it simple" icon="minimize">
    Start with minimal data models and expand as needed
  </Card>
</CardGroup>

### Input and output design

**DO:**

✅ Define only required input parameters in the input parameters\
✅ Use meaningful parameter names that describe the data\
✅ Set appropriate data types for validation\
✅ Mark parameters as required when they're essential

**DON'T:**

❌ Include unnecessary data in input/output parameters\
❌ Use ambiguous or cryptic parameter names\
❌ Make all parameters optional when some are required\
❌ Change data model structure without updating mappings

### Node naming

<Tip>
  Use descriptive node names that indicate their purpose:

  * ✅ `FetchCustomerData`, `ValidateCreditScore`, `TransformResponse`
  * ❌ `Node1`, `Node2`, `Script`
</Tip>

The system enforces unique node names within workflows. If you need similar operations, use descriptive suffixes:

* `FetchCustomerData_Personal`
* `FetchCustomerData_Financial`

***

## Limitations and compatibility

### Current limitations

<Warning>
  The following features are **not yet available**:
</Warning>

* **Start sub-workflow node**: Start sub-workflow nodes work as-is without data model integration
* **Endpoint schema integration**: Imported Swagger schemas are not integrated with workflow data models yet
* **Database schema mapping**: Database operation schemas are not mapped to workflow variables yet

***

## Related resources

<CardGroup>
  <Card title="Integration Designer Overview" href="./integration-designer" icon="book-open">
    Learn about Integration Designer workflows and nodes
  </Card>

  <Card title="Process Data Model" href="../../building-blocks/process/data-model" icon="database">
    Understand Process Data Models and how they work
  </Card>

  <Card title="Data Mappers" href="../../building-blocks/process/data-mappers" icon="diagram-project">
    Configure data mappings between processes and workflows
  </Card>

  <Card title="Start Integration Workflow Action" href="../../building-blocks/actions/start-integration-workflow-action" icon="play">
    Invoke workflows from process definitions
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Start Node input is empty after defining input parameters">
    **Possible causes:**

    * Input parameters not saved correctly
    * Browser cache issues
    * No input parameters defined (results in empty object)

    **Solutions:**

    * Save the workflow and refresh the browser
    * Re-open the workflow diagram tab
    * Check that the input parameters contains attributes
    * Verify attributes are marked as required if needed
    * If no input parameters are defined, the Start Node will contain an empty object `{}`
  </Accordion>

  <Accordion title="Manual changes to Start Node JSON are lost">
    **Problem:** You manually edited the JSON in the Start Node, but your changes disappeared after refreshing or reopening the workflow.

    **Cause:**
    The Start Node is automatically populated from the input parameters definition. Any manual edits are overwritten when the workflow diagram is refreshed or reopened.

    **Solution:**

    * Update the input parameters definition in the **Input/Output Parameters** tab instead of editing the Start Node JSON directly
    * Changes to the input parameters will automatically reflect in the Start Node
    * If you need a different structure, modify the data model and input parameters accordingly
  </Accordion>

  <Accordion title="Node name uniqueness validation error">
    **Error message:** "Node name must be unique within the workflow"

    **Solution:**

    * Choose a different, more descriptive node name
    * The system will suggest appending an index (e.g., `_2`)
    * Use descriptive suffixes instead (e.g., `_Personal`, `_Financial`)
  </Accordion>

  <Accordion title="Data mapper not working after adding data model">
    **Possible causes:**

    * Input parameters keys don't match process data mapper
    * Data types mismatch

    **Solutions:**

    * Ensure data mapper keys match input parameters attribute names exactly
    * Verify data types are compatible (string to string, number to number)
    * Check for typos in attribute names
    * Review process data model to workflow data model mapping
  </Accordion>

  <Accordion title="Cannot delete entity or attribute">
    **Error message:** "Entity/Attribute is referenced and cannot be deleted"

    **Solution:**

    * Check attribute usages using the API: `GET .../attributes/{name}/usages`
    * Remove references from input/output parameters first
    * Update workflow nodes that use the attribute
    * Then retry deletion
  </Accordion>
</AccordionGroup>


# FlowX custom plugins
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins

Adding new capabilities to the core platform can be done by using plugins. FlowX plugins represent already-built functionality that can be added to a FlowX.AI platform deployment.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/plugins_40.png)

These could be either one of the provided custom **plugins** that we've already built or building your desired plugin.

On our roadmap, we’re also looking to enhance the **plugins library** with 3rd party providers, so stay tuned for more.

## High-level architecture

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/plugins_diagram.png)

The plugins are microservice apps that can be developed using any tech stack. The only requirement is that they need to be able to connect to the core platform using Kafka events.

<Card title="Introduction to Kafka" href="../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts" icon="file" />

<Card title="Send message task (Kafka)" href="../../building-blocks/node/message-send-received-task-node#send-message-task" icon="file" />

<Card title="Receive message task (Kafka)" href="../../building-blocks/node/message-send-received-task-node#receive-message-task" icon="file" />

To interact with plugins, you need to understand a few details about them:

* the events that can trigger them
* the infrastructure components needed
* the needed configurations

## Custom plugins

The currently available plugins are:

* [**OCR**](./custom-plugins/ocr-plugin) - helps you scan your documents and integrate them into a business process
* [**Reporting**](./custom-plugins/reporting/reporting-overview) - a plugin that will help you create and bootstrap custom reports built on generic information about usage and processes metrics

Let's get into a bit more detail about the custom plugins 🎛️

## OCR plugin

**Automatic key information extraction**

Used to easily read barcodes or extract handwritten signatures from PDF documents.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_plugin_archi.svg)
</Frame>

<Card title="More about OCR plugin" href="./custom-plugins/ocr-plugin" icon="file" />

## Reporting plugin

**Easy-to-read dynamic dashboards**

Use reporting plugin to build and bootstrap custom reports built on generic information about usage and processes.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/reporting_diag.png)
</Frame>

<Card title="More about Reporting plugin" href="./custom-plugins/reporting/reporting-overview" icon="file" />


# OCR plugin
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins/ocr-plugin

The OCR (Optical Character Recognition) plugin is a tool that enables you to read barcodes and extract handwritten signatures from .pdf documents.

Before using the OCR service for reading barcodes and extracting signatures, please note the following requirements:

<Info>
  * All \*.pdf documents that are sent to the OCR service for reading barcodes and extracting handwritten signatures should be scanned at a minimum resolution of 200DPI (approximately 1654x2339 px for A4 pages)
  * Barcode is searched on the top 15% of each image (scanned page)
  * Signatures are detected on boxes with a border: 4px black solid
  * Only two signatures per image (scanned page) are detected.
</Info>

<Info>
  The plugin supports **1D Code 128** barcodes. For more information, see the [Code 128 documentation](https://graphicore.github.io/librebarcode/documentation/code128.html).
</Info>

## Using the OCR plugin

You can utilize the OCR plugin to process generic document templates by either using a specific flow on FlowX.AI (HTML template) or any other document editor.

<Tip>
  Using a specific flow on FlowX.AI offers several advantages:

  * Centralized management of templates and flows within a single application.
  * Access to template history and version control.
</Tip>

### Use case

1. Prepare and print generic document templates.
2. End-users complete, sign, and scan the documents.
3. Upload the scanned documents to the flow.
4. FlowX.AI validates the template (barcode) and the signatures.

### Scenario for FlowX.AI generated documents

1. Utilize the [**Documents plugin**](../../core-extensions/content-management/documents-plugin/documents-plugin-overview) to create a [**document template**](../../core-extensions/content-management/documents-plugin/generating-from-html-templates).

<Card title="Generating documents based on templates" href="../../core-extensions/content-management/documents-plugin/generating-from-html-templates" icon="file" />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_doc_template.gif)

2. Create a process and add a [**Kafka Send Action**](../../../building-blocks/node/message-send-received-task-node#configuring-a-message-send-task-node) to a [**Send Message Task**](../../../building-blocks/node/message-send-received-task-node#send-message-task) node. Here you specify the [**Kafka topic**](../../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts#topics) (address) where the template will be generated.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_kafka_send.png)
</Frame>

<Info>
  The Kafka topic for generating the template must match the topic defined in the **`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN`** variable. Refer to the [**Kafka configuration guide**](../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka) for more details. For additional information, please see the [**Documents plugin setup guide**](../../../../setup-guides/documents-plugin-setup).
</Info>

3. Fill in the **Message**. The request body should include the following values:

* **documentList** - a list of documents to be generated, including properties such as name and values to be replaced in the document templates
* **customId** - client ID
* **templateName** - the name of the template to be used
* **language**
* **includeBarcode** - true/false
* **data** - a map containing the values that should replace the placeholders in the document template, the keys used in the map should match those defined in the HTML template

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_message_body.png)
</Frame>

<Info>
  The `data` parameters must be defined in the document template beforehand. For more information, check the [**document template**](../../core-extensions/content-management/documents-plugin/generating-from-html-templates) section.

  <Frame>
    ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_data_model.png)
  </Frame>
</Info>

4. Add a **barcode**.

<Check>
  * to include a **default barcode**, add the following parameter to the message body: `includeBarCode: true`.
  * to include a **custom barcode**, set `includeBarCode: false` and provide the desired data in the `data` field
</Check>

5. Add a [**Receive Message Task**](../../../building-blocks/node/message-send-received-task-node#receive-message-task) node and specify the topic where you want to receive the response.

<Check>
  Ensure that the topic matches the one defined in the **`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT`** variable.
</Check>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_receive_response.png)
</Frame>

6. Add a [**User Task**](../../../building-blocks/node/user-task-node) node and configure an [**Upload file**](../../../building-blocks/actions/upload-file-action) action to send the file (defined by the **`KAFKA_TOPIC_DOCUMENT_PERSIST_IN`** variable) to the storage solution (for example, S3).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_upload_file.png)
</Frame>

7. Next, the response will be sent back to the Kafka topic defined by **`KAFKA_TOPIC_DOCUMENT_PERSIST_OUT`** environment variable through a callback action/subprocess.
8. Next, send the response to the OCR Kafka topic defined at **`KAFKA_TOPIC_OCR_IN`** variable (representing the path to the S3 file).
9. Display the result of the OCR validation in the Kafka topic defined at **`KAFKA_TOPIC_OCR_OUT`**.

For the OCR request and response message formats, refer to the [OCR plugin setup guide](../../../../setup-guides/plugins-setup-guide/ocr-plugin-setup).

<Info>
  The env vars above (`KAFKA_TOPIC_OCR_IN`, `KAFKA_TOPIC_OCR_OUT`) are configured on the **Document Plugin** side. The standalone **OCR Plugin** uses its own env vars (`KAFKA_INPUT_TOPIC`, `KAFKA_OUTPUT_TOPIC`) — see the [OCR plugin setup guide](../../../../setup-guides/plugins-setup-guide/ocr-plugin-setup#kafka-configuration) for details.
</Info>

### Setup guide

<Card title="OCR plugin setup" href="../../../../setup-guides/plugins-setup-guide/ocr-plugin-setup" icon="gears">
  Refer to the OCR plugin setup guide for detailed instructions on setting up the OCR plugin.
</Card>


# Authorization & access roles
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins/reporting/access-and-authorization

Configure authorization and access roles for the Reporting plugin using Keycloak integration with Apache Superset.

## IAM solution

<Info>
  Superset is using by default flask-openid, as implemented in flask-security.
</Info>

Superset can be integrated Keycloak, an open-source identity and access management solution. This integration enables users to manage authentication and authorization for their Superset dashboards.

<Card title="Configuring an IAM solution" href="../../../../../setup-guides/access-management/configuring-an-iam-solution" icon="link" />

### Prerequisites

* Keycloak server
  * Keycloak Realm
  * Keycloak Client & broker configured with OIDC protocols
  * client\_secret.json
* admin username & password of postgres instance
* Superset Database created in postgresql
* optionally Cert-manager if you want to have SSL certificates on hostnames.

<Card title="Superset + Keycloak configuration" href="../../../../../setup-guides/plugins-setup-guide/reporting-setup#keycloak-configuration" icon="link" />


# Reporting plugin
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins/reporting/reporting-overview

Build custom and technical reports from BPMN process data and process instance data, integrated with the FlowX.AI Engine.

### Quick walkthrough video

Watch this quick walkthrough video to get started:

<Frame>
  <video />
</Frame>

### Data exploration and visualization

The plugin uses **Superset** as a free data exploration and visualization tool.

<Tip>
  You can however use your own BI tool like Tableau, PowerBI etc. as an alternative to Superset.
</Tip>

Use the suggested query structure and logic to ensure accurate reporting and avoid duplicates, even during database updates. Do not just use select on single reporting tables.

<Frame>
  ![Reporting plugin overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/reporting.png)
</Frame>

Apache Superset is an open-source software application for data exploration and data visualization able to handle data at a large scale. It enables users to connect their company's databases and perform data analysis, and build charts and assemble dashboards.

Superset is also an SQL IDE, so you can write SQL, join data, create datasets, and more.

<Card title="Superset documentation" href="https://superset.apache.org/docs/intro/" icon="book" />

### Plugin architecture

Here’s an overview of the reporting plugin architecture:

<Frame>
  ![Reporting plugin architecture diagram](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Reporting_diagram_small2.png)
</Frame>

### Setting up reporting for a process definition

<Steps>
  <Step title="Establish reporting data model to be extracted from process">
    If you want to extract custom business parameters for a process, first you should set up the master reporting data model in the published version of that process. This is done in Designer, as explained below in the [**Reporting Data Model**](#reporting-data-model).

    The master reporting data model that is applied to all historical versions is the one belonging to the version that is set as Published. If the currently published version is read-only, you might need to create a new version, create the data model in it, mark it for reporting and set it as published (as explained in the section below).

    See [**Reporting Data Model**](#reporting-data-model) section for more details.
  </Step>

  <Step title="Enable reporting on the process versions to be reported">
    This is accomplished by checking the “Use process in reporting” button in the settings / general page of each process version you want to report. Please note that you will not be able to change that setting on read-only versions.

    <Frame>
      ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/use_proc_reporting.gif)
    </Frame>

    It is essential that the currently Published version has this setting enabled, as it is the master version for reporting all historical data.

    Only the process instances belonging to reporting-enabled versions will be extracted to the database, using the master data model from the currently Published version.

    <Info>
      The reason why you should first set up the data model on the published (or to-be-published) version is that all changes in the data model of the published version that is also marked “use\_in\_reporting” are instantly sent to the reporting plugin, potentially causing all historical process instances to be re-computed multiple times before you are done setting up the data model.
    </Info>

    To optimize operations, you should always aim to finish the modifications on the master data model on a version that is either not published, or not marked as "use\_in\_reporting", before marking it as "use\_in\_reporting and ensuring it is published.

    See [**Enabling Process Reporting**](#enabling-process-reporting) section for more details.
  </Step>
</Steps>

## Reporting data model

<Info>
  You can only create or modify the reporting data model in non-committed versions, as committed versions are read-only.
</Info>

1. Open the branch view.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/branching_view.png)
</Frame>

2. If the current project version is committed, start a new version.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_new_version.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/rep6.png)
</Frame>

3. Make sure the new work-in-progress branch is selected, then go back to the process definition page.
4. Click on the Data Model icon and navigate in the object model to the target parameters.
5. Set up the business data structure to be reported by using the "Use in reporting" flag.

* Click "Show details".
* Click "Use in reporting".

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/data_to_be_reported.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flag_use_in_reporting.gif)
</Frame>

You can do this also for each parameter individually.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/parameter_type.png)
</Frame>

<Info>
  There are three parameter structures that you can report:

  **Singleton** or primitive, for which a single value is saved for each process instance. They can be of the types number, string or Boolean and will all be found in the reporting table named `params_{process_alias}`.

  **Array of primitives**, in which several rows are saved for each process instance, in a dedicated table (one value per row).

  **Array of objects**, in which the system extracts one or more “leaves” from each object of an array of objects. Also saved as a dedicated table.
</Info>

### Primitive parameters reporting

In the following example, there are 3 simple parameters that will be extracted: `loan_approvalFee`, `loan_currency` and `loan_downPayment`.
They will be reported in the table `params_{process_alias}`, one row per instance.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/primitive_parameters_reporting.png)
</Frame>

### Arrays of primitives reporting

In the following example, the applicant can submit more than one email address, so each email will be extracted to a separate row in a dedicated table in the reporting database.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/arrays_of_primitives.png)
</Frame>

<Warning>
  Extracting arrays is computationally intensive, do not use them if the only purpose is just to aggregate them afterward. Aggregation should be performed in the process, not in the reporting stage.
</Warning>

### Array of objects reporting

In this example, the applicant can have several real estate assets, so a subset of data items (`currentValue`, `mortgageBalance`, `propertyType`) will be extracted for each one of them.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/array_of_objects.png)
</Frame>

<Warning>
  Extracting arrays of objects is even more is computationally intensive, do not use them if the only purpose is just to aggregate them afterward. Aggregation should be performed in the process, not in the reporting stage.
</Warning>

## Enabling process reporting

Enable reporting by checking the “Use process in reporting” button on the settings/general page of each process.

* Modifying the data model of a process version has no impact until the moment the version or build of the project is set in the "Active policy" tab and is also set to "use\_in\_reporting".

The reporting refresh schedule is set for a fixed interval (currently 5 minutes):

* No processing overlaps are allowed. If processing takes more than 5 minutes, the next processing is automatically postponed until the current one is finished.
* The number of Spark executors is automatically set by the reporting plugin depending on the volume of data to be processed, up to a certain fixed limit that is established in the cloud environment. This limit can be adapted depending on your needs.
* Rebuilding the whole history for a process (if the master data model, process name or the Published version change) typically takes more time. It is better to make these changes after the working hours.

## Reporting database

### Main tables

Common fields for joins:

* `inst_id`: Unique identifier for each process instance
* `query_time`: Timestamp for when the plugin extracts data

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/rep20.png)
</Frame>

**Useful fields from instances table**:

* `date_started/finished` timestamps
* `process_alias` (process name with "\_" instead of spaces)

<Info>
  The published version alias will be used for all the reported versions.
</Info>

* State of the process (started, finished, etc.)
* `context_name`: Useful if the process is started by another process

**Useful fields from current\_nodes table**:

* `node_started/finished` timestamps for the nodes
* `node_name`, `node_type`
* `swimlane` of the current node
* `prev_node_end`: For calculating when a token is waiting for another process branch

**Useful fields from token\_history table**:

Similar to `current_nodes` but includes all nodes in the instance history.

### Parameters and object tables

Common fields, on which the joins are built:

* `inst_id`, unique identifier for each process instance
* `query_time`, recorded at the moment the plugin extracts data from the database

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/reporting30.png)
</Frame>

For the `params_` table, there is a single row per process instance. For arrays and arrays of objects tables, there are multiple rows per process instance.

## Using Superset for data exploration

### Data sources

The **Data** tab represents the sources of all information:

* Databases
* CSV files
* Tables
* Excel files

Reporting plugin can be used with Superset by connecting it with a PostgreSQL DB.

### Charts

Charts represent the output of the information. There are multiple visualization charts/ plugins available.

### Dashboards

With the use of dashboards, you can share persuading flows, show how metrics change in various scenarios and match your company efforts with logical, evidence‐based visual indicators.

### Datasets

Contains all the information for extracting and processing data from the DB, including SQL queries, calculated metrics information, cache settings, etc. Datasets can also be exported / imported.

### Connecting to a database

Before using Superset, ensure you have a PostgreSQL database installed and configured. Follow these guides for setup:

[FlowX Engine DB configuration](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup)

[Reporting DB configuration](../../../../../setup-guides/plugins-setup-guide/reporting-setup)

<Info>
  Read-only users should be used in production in the reporting-plugin cronjob.
</Info>

To connect Superset to a database, follow the next steps:

1. From the Toolbar, hover your cursor over the **"+"** icon, then select **Data**, and then select **Connect Database**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/connecting_to_db.png)
</Frame>

2. The **Connect a database** window appears. Select the appropriate **database card** (in this case - PostgreSQL).

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/connect_db_superset.png)
</Frame>

3. After you selected the DB, click **Connect this database with a SQLAlchemy URI string instead?**.
4. Fill in the **SQLALCHEMY URI** and then click **Connect**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_db_URI.png)
</Frame>

<Info>
  The **SQLAlchemy URI** for **reporting-db** should be in this format: `postgresql://postgres:XXXXXXXXXX@reporting-plugin-postgresql:{{port}}/reporting`.
</Info>

### Creating and configuring charts

There are multiple ways in which you can create/configure a chart.

#### Creating charts using Datasets tab

To create a Chart using the first method, you must follow the next steps:

1. From the top toolbar, select **Data** and then **Datasets**.

<Check>
  You need to have a dataset added to Superset first. From that particular dataset you can build a visualization.
</Check>

2. Select the desired **dataset**.
3. On the **explore** page, choose the **visualization type** and click **Create chart**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_add_chart.gif)
</Frame>

4. When you select a dataset, by default **table** visualization type is selected.

<Info>
  To view all the existent visualization types, click **View all charts**, the charts' gallery will open.
</Info>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_visualization_type.png)
</Frame>

#### Creating charts using Chart gallery

Using the Chart gallery is a useful method when you are not quite sure about which chart will be best for you.

To create a Chart using the second method, you must follow the next steps:

1. Select the **"+"** icon from the top toolbar and choose **Chart**.
2. Choose the **dataset** and **chart type**.
3. Review the description and example graphics of the selected chart, then click **Create new chart**.

<Tip>
  If you wish to explore all the chart types available, filter by **All charts**. The charts are also grouped by categories.
</Tip>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_add_chart_second.gif)
</Frame>

### Configuring a Chart

Configure the **Query** fields by dragging and dropping relevant columns to the matching fields. Note that time and query form attributes vary by chart type.

### Exporting/importing a Chart

You can export and import charts to help you analyze your data and manipulate dashboards. To export/import a chart, follow the next steps:

1. Open **Superset** and navigate to **Charts** from the top navigation bar.
2. Select the desired **chart** and click the **breadcrumbs** menu in the top-right corner.
3. Choose an export option: .CSV, .JSON, or Download as image.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/reporting_export_imp.png)
</Frame>

**Table example**:

* **Time** - time related form attributes
* **Query** - query attributes
  * **Dimensions** - one or many columns to group by
  * **Metrics** - metrics to display
  * **Percentage metrics** - metrics for which percentage of total are to be displayed, calculated from only data within the row limit
  * **Filters** - metric used for filtering
  * **Sort by** - metric used to define how the top series are sorted if a series or row limit is present
  * **Row limit** - limits the number of rows that get displayed

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_query.png)
</Frame>

### Creating a dashboard

To create a dashboard follow the next steps:

1. Create a new chart and save it to a new dashboard.
2. To publish, click **Save and go to Dashboard**.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/save_dashboard.gif)
</Frame>

For details on how to configure the FlowX.AI reporting plugin, check the following section:

<Card title="Reporting setup guide" href="../../../../../setup-guides/plugins-setup-guide/reporting-setup" icon="gear" />


# WYSIWYG editor
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/wysiwyg

Create and edit notification and document templates in FlowX Designer with the WYSIWYG (What You See Is What You Get) editor.

Displaying how the document will be published or printed on the screen, the user can adjust the text, graphics, photos, or other document/notification elements before generating the final output.

## WYSIWYG Components

### Header

The formatting head of the editor allows users to manipulate/format the content of the document.

### Body

The Body is the main part of the editor where you can edit your template.

<Tip>
  After you defined some parameters in the **Data Model** tab, you can type "**#**" in the body to trigger a dropdown where you can choose which one you want to use.
</Tip>

### Source

The **Source** button can be used to switch to the HTML editor. You can use the HTML view/editor as a debugging tool, or you can edit the template directly by writing code here.

![Source Code](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_source.gif)

## Document templates

One of the main features of the [document management plugin](../core-extensions/content-management/documents-plugin/documents-plugin-overview) is the ability to generate new documents based on custom templates and prefilled with data related to the current process instance.

![Document template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_document_template.png)

<Card title="Documents plugin" href="../core-extensions/content-management/documents-plugin/documents-plugin-overview" icon="file" />

## Notification templates

Notification WYSIWYG body has some additional fields (other than documents template):

* **Type** - that could be either MAIL or SMS (SMS, only if there is an external adapter)
* **Forward on Kafka** - if this box is checked, the notification is not being sent directly by the plugin to the destination, but forwarded to another adapter

![Notification template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_notif_template.png)

<Card title="Managing notifications templates" href="../core-extensions/content-management/notifications-plugin/managing-notification-templates" icon="file" />

## Data model

Using the data model, you can define key pair values (parameters) that will be displayed and reused in the body. Multiple parameters can be added:

* STRING
* NUMBER
* BOOLEAN
* OBJECT
* ARRAY (which has an additional `item` field)

![Data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_data_model.png)

<Info>
  Parameters can be defined as mandatory or not. When you try to generate a template without filling in all the mandatory parameters, the following error message will be displayed: "*Provided data cannot be empty if there are any required properties defined."*
</Info>


# Third-party components
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/third-party-components

FlowX.AI uses a number of third-party software components

## Overview

FlowX.AI relies on various third-party components to deliver its functionality. These components fall into two categories:

* **Embedded components**: Third-party software packaged and managed by FlowX.AI
* **Client-managed components**: Third-party software that you deploy and maintain

<Info>
  For optimal performance and reliability, our internal QA process validates new releases using specific versions. While you can explore alternative versions that suit your requirements, we recommend referring to the compatibility matrix for guidance.
</Info>

<Note>
  Licensing of third-party components is governed by each vendor and may change over time. Consult each vendor's official licensing documentation for current terms.
</Note>

## Embedded components

<Note>
  Embedded components are shipped and configured as part of the FlowX.AI platform. FlowX.AI manages their versioning, patching, security updates, and provides L4 support coverage. They are deployed alongside the platform using the standard FlowX.AI deployment process.
</Note>

### Authorization

<CardGroup>
  <Card title="SpiceDB" icon="shield" href="https://authzed.com/spicedb">
    An open-source permissions database inspired by Google's Zanzibar paper. Powers FlowX.AI's multi-tenant authorization system with fine-grained access control and relationship-based permissions.

    **Key capabilities**: Google Zanzibar-inspired authorization, ReBAC, global consistency, reverse lookup, sub-millisecond response times
  </Card>

  <Card title="SpiceDB Operator" icon="gears" href="https://github.com/authzed/spicedb-operator">
    A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. Handles upgrades, scaling, and configuration changes for consistent and reliable SpiceDB deployments.
  </Card>

  <Card title="Qdrant" icon="cube" href="https://qdrant.tech/documentation/">
    **Supported Version**: 1.16.3

    Vector search engine used by the AI Platform RAG path (knowledgebase-rag, embedder, knowledgebase-indexer-v2) and by AI agents for semantic retrieval. Required for AI Platform deployments starting with 5.9.0.
  </Card>
</CardGroup>

## Client-managed components

<Info>
  Client-managed components are deployed and maintained by your team. FlowX.AI validates compatibility with supported versions listed in the [compatibility matrix](#compatibility-matrix) but does not provide direct support for these components.
</Info>

### Core infrastructure

<Tabs>
  <Tab title="Identity & access">
    <Card title="Keycloak" icon="key" href="https://www.keycloak.org/documentation">
      **Supported Version**: 26+

      Open-source identity and access management solution enabling single sign-on for modern applications.
    </Card>
  </Tab>

  <Tab title="Messaging">
    <CardGroup>
      <Card title="Apache Kafka" icon="message-dots" href="https://kafka.apache.org/documentation/">
        **Supported Versions**: 3.9 – 4.2

        Distributed event streaming platform for high-volume, real-time data feeds with fault tolerance and low latency.
      </Card>

      <Card title="Kafka Connect" icon="plug" href="https://kafka.apache.org/documentation/#connect">
        **Supported Version**: matches the deployed Kafka cluster version

        Streaming integration framework for moving data between Kafka and other systems. Used by the FlowX.AI integration paths that source or sink events to external stores.
      </Card>

      <Card title="Elasticsearch Sink Connector" icon="arrows-turn-to-dots" href="https://docs.confluent.io/kafka-connectors/elasticsearch/current/overview.html">
        **Supported Version**: 15+

        Kafka Connect sink plugin that streams process-instance events into Elasticsearch indices. Required only if you enable indexing via Kafka in the process engine. Other sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch versions. See [Configuring Elasticsearch indexing](/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing).
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Databases">
    <CardGroup>
      <Card title="PostgreSQL" icon="database" href="https://www.postgresql.org/docs/">
        **Supported Versions**: 16 – 18

        Free and open-source relational database emphasizing extensibility and SQL compliance.
      </Card>

      <Card title="MongoDB" icon="database" href="https://www.mongodb.com/docs/">
        **Supported Versions**: 7 – 8

        Document-oriented NoSQL database for business process data and configuration storage.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Caching & storage">
    <CardGroup>
      <Card title="Redis" icon="fire" href="https://redis.io/docs/">
        **Supported Version**: 8.2+

        Fast in-memory key-value store for caching and pub/sub messaging with sub-millisecond response times.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

### Infrastructure & monitoring

<AccordionGroup>
  <Accordion title="Web server & load balancing">
    **NGINX Ingress Controller**

    Kubernetes ingress controller for routing web traffic from SPAs to backend services and the FlowX.AI Engine.

    <Note>
      Starting with 5.9.x, the FlowX.AI chart no longer assumes ingress-nginx as the bundled controller. Kubernetes Ingress remains fully supported with any compliant controller (Traefik, HAProxy, Istio, cloud-provider controllers), and Gateway API HTTPRoutes are supported as an alternative. See [Ingress routing and CORS changes](/5.9/migrating-from-5.1-lts/ingress-routing).
    </Note>

    <Card title="ingress-nginx documentation" href="https://kubernetes.github.io/ingress-nginx/" icon="external-link" />
  </Accordion>

  <Accordion title="Search & analytics">
    **Elasticsearch (EFK Stack)**\
    **Version**: 8.x

    Distributed search and analytics engine for centralized data storage and business process transaction searching.

    <CardGroup>
      <Card title="Elastic Stack" href="https://www.elastic.co/elastic-stack/" icon="external-link" />

      <Card title="Fluentd" href="https://docs.fluentd.org/" icon="external-link" />
    </CardGroup>
  </Accordion>

  <Accordion title="Business intelligence">
    **Apache Superset**

    Business intelligence web application for data exploration and visualization, from simple charts to detailed dashboards.

    <Card title="Superset documentation" href="https://superset.apache.org/docs/intro" icon="external-link" />
  </Accordion>
</AccordionGroup>

### Commercial components

<Card title="Oracle Database" icon="database" href="https://www.oracle.com/database/technologies/">
  **Supported Versions**: 21c, 23ai

  Enterprise relational database management system for mission-critical workloads.

  <Note>
    Oracle Database requires commercial licensing. Contact Oracle for licensing information.
  </Note>
</Card>

## Compatibility matrix

### Third-party open-source components

| Component                         | Supported Versions                                                       |
| --------------------------------- | ------------------------------------------------------------------------ |
| Keycloak                          | 26+                                                                      |
| Kafka                             | 3.9 – 4.2                                                                |
| Kafka Connect                     | matches Kafka                                                            |
| Elasticsearch Sink Connector (\*) | 15+                                                                      |
| PostgreSQL                        | 16 – 18                                                                  |
| MongoDB                           | 7 – 8                                                                    |
| Redis                             | 8.2+                                                                     |
| Ingress controller                | any Ingress-compliant controller (Gateway API HTTPRoutes also supported) |
| Elasticsearch                     | 8.x                                                                      |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version deployed.

### Renderer SDKs

| SDK               | Supported Version |
| ----------------- | ----------------- |
| Angular (Web SDK) | 20.3              |
| React (Web SDK)   | 19                |

### Commercial components

| Component       | Supported Versions |
| --------------- | ------------------ |
| Oracle Database | 21c, 23ai          |

## Deprecation notice

<Warning>
  The following versions are no longer supported. Versions are dropped from the supported list as support upstream is no longer provided.

  * Keycloak versions older than 26
  * Kafka versions older than 3.9 (3.8 dropped in 5.9.0)
  * Redis versions older than 8.2 (8.0 deprecated upstream)
</Warning>

## Support information

<Info>
  **LTS support policy.** FlowX 5.9.x LTS family is supported for 2 years. Within that window, support for any third-party dependency is contingent on that dependency remaining supported by its upstream vendor. Once a version reaches upstream end-of-life, it is removed from the supported list and customers are expected to upgrade to a still-supported version, even if the FlowX LTS itself remains supported.
</Info>

<Info>
  If you encounter compatibility issues with any of the supported versions listed above, please [open a support ticket](https://support.flowx.ai/) and our team will address any identified bugs through our standard support process.
</Info>

## Related resources

<CardGroup>
  <Card title="Event-driven Architecture" href="../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts" icon="book">
    Learn about Kafka concepts and implementation
  </Card>

  <Card title="NGINX Configuration" href="../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx" icon="book">
    Understanding NGINX in FlowX.AI architecture
  </Card>

  <Card title="Data Architecture" href="../platform-overview/data-architecture" icon="database">
    Which data stores FlowX.AI uses and what each stores
  </Card>
</CardGroup>


# Anonymous runtime access
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access

Run processes and UI flows for unauthenticated users using the built-in Anonymous role and the Share modal's public-access option.

<Info>
  A runtime app can be configured for unauthenticated end users. Anonymous users start processes and UI flows from a public link, with no login required.
</Info>

## Overview

Anonymous runtime access lets an app serve users who have no FlowX identity. A typical use case is a public form, a quote calculator, or an appointment booking page reachable from a marketing site.

Two independent gates must both be open for a request to be served anonymously:

<Steps>
  <Step title="The app must be shared publicly">
    In the Share modal, **General access** is set to **Everyone with the link**. Apps default to **Only invited users and groups**.
  </Step>

  <Step title="The resource must allow the Anonymous role">
    The specific process or UI flow being started must have the **Anonymous** role assigned in its Permissions tab.
  </Step>
</Steps>

If either gate is closed, the runtime returns `403 Forbidden` with a `detail` of `Anonymous access not enabled for this application` (the app is not publicly shared) or `Anonymous access not enabled for this build` (the resource does not carry the Anonymous role). Mixed-access is supported — the same app can serve authenticated users with their assigned roles and anonymous users with the Anonymous role.

<Frame>
  ![Public-access toggle in the Share modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/anonymous-share-modal.png)
</Frame>

***

## The Anonymous role

`Anonymous` is a **built-in, system-level role**. It represents any user who arrives without a valid authentication token.

| Property                            | Value                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------ |
| **Role type**                       | System (built-in)                                                        |
| **Editable**                        | No — name, scope, and allowed operations are fixed                       |
| **Deletable**                       | No                                                                       |
| **Allowed operations**              | `VIEW`, `EXECUTE`, `SELF_ASSIGN`                                         |
| **Selectable operations in the UI** | `VIEW` and `EXECUTE` only — `SELF_ASSIGN` is auto-populated and required |
| **Default on a project**            | Not added — admin opts in via **End User Roles** in Version settings     |

<Info>
  `SELF_ASSIGN` is required because starting a process needs both `EXECUTE` and `SELF_ASSIGN`. The role auto-populates the three operations and locks `SELF_ASSIGN` so the role always behaves consistently across processes.
</Info>

***

## Make an app publicly accessible

<Steps>
  <Step title="Add the Anonymous role to the project">
    Open the project's **Version settings → End User Roles**, then add **Anonymous** to the available roles.

    Until the role is on the version, the Share modal's general-access dropdown stays disabled.
  </Step>

  <Step title="Open the Share modal">
    From the project header, click **Share**.
  </Step>

  <Step title="Set General access to Everyone with the link">
    Under **Who has access → General access**, switch from **Only invited users and groups** to **Everyone with the link**.

    <Tip>
      Switching back to **Only invited users and groups** at any point closes the public gate immediately. Existing anonymous sessions in flight will start returning `403 Anonymous access not enabled for this application` on their next request.
    </Tip>
  </Step>

  <Step title="Save and copy the share link">
    Save the Share modal. The runtime app is now reachable to anyone with the URL — subject to the per-resource role check below.
  </Step>
</Steps>

***

## Configure anonymous on a resource

The Anonymous role must be explicitly assigned to each process, UI flow, or reusable UI template you want runnable without authentication.

<Tabs>
  <Tab title="Process">
    Open the process and go to **Permissions**.

    1. Add **Anonymous** to the role list (only available when the role is on the version).
    2. The role's row shows `VIEW`, `SELF_ASSIGN`, and `EXECUTE` pre-populated. Toggle `VIEW` or `EXECUTE` as needed. All other operations are greyed out.
    3. Adding Anonymous is **additive** — it does not affect other roles on the process.

    Anonymous can also be added to a swimlane. The component hide/disable rules below depend on this assignment.
  </Tab>

  <Tab title="UI Flow">
    Open the UI flow and go to **Settings → Permissions**.

    Add **Anonymous** to the role list. The same additive behaviour applies — other roles are preserved.

    Anonymous on a UI flow is required for that flow to be startable from a public URL, and for any integration workflows started from inside the flow to be reachable anonymously.
  </Tab>

  <Tab title="Reusable UI template">
    Reusable UI templates inherit role availability from **Process Version → End User Roles**. Once Anonymous is added there, it becomes selectable as a role-based hide/disable condition inside the template.
  </Tab>
</Tabs>

***

## Component visibility for anonymous users

UI Designer hide/disable rules support the Anonymous role in the **Role** condition type. The role must already be assigned at the right scope:

| Component lives in…    | Anonymous must be on…                    |
| ---------------------- | ---------------------------------------- |
| A process node         | The corresponding **swimlane**           |
| A UI flow              | The UI flow's **Permissions** tab        |
| A reusable UI template | The process version's **End User Roles** |

Common patterns:

* **Hide for anonymous** — show a "Sign in to continue" CTA only when the user is anonymous; hide an action button (e.g. "Save to account") for anonymous users.
* **Disable for anonymous** — keep a field visible but read-only; the same field becomes editable for authenticated users.

***

## Runtime behaviour scenarios

| #  | App general access            | Resource has Anonymous role               | User                                              | Outcome                                                                                                                       |
| -- | ----------------------------- | ----------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 1a | Everyone with the link        | Yes                                       | Anonymous                                         | Starts and uses the resource with Anonymous permissions.                                                                      |
| 1b | Everyone with the link        | Yes (Anonymous is the only role)          | Authenticated                                     | Starts with the same permissions Anonymous grants — the logged-in user is effectively treated as anonymous for that resource. |
| 1c | Everyone with the link        | Yes (Anonymous + at least one other role) | Authenticated and assigned one of the other roles | Uses the assigned role; Anonymous is ignored.                                                                                 |
| 2a | Only invited users and groups | n/a                                       | Anonymous                                         | `403` — `Anonymous access not enabled for this application`                                                                   |
| 2b | Everyone with the link        | No                                        | Anonymous                                         | `403` — `Anonymous access not enabled for this build`                                                                         |

***

## The anonymous session

Anonymous traffic is isolated using a session ID — there is no user identity to bind state to.

* **Header:** `X-Fx-Anonymous-Session-Id`
* **Issued by:** the backend, on the first anonymous request that doesn't already carry one. The new session ID comes back in the response header `X-Fx-Anonymous-Session-Id` (exposed via `Access-Control-Expose-Headers`; the exposed-header list is controlled by the `APPLICATION_CORS_EXPOSEDHEADERS` env var, which carries this header by default).
* **Maintained by:** the SDK / container app. After receiving the session ID, the client must include it on every subsequent anonymous request.
* **Scope:** one anonymous session can only access the process and UI flow instances it created. Another session that knows the `processInstanceUuid` cannot read or act on it.
* **Lifetime:** fire-and-forget. Closing the browser ends the session. There is no resume mechanism in 5.9.0.

<Warning>
  **Tokens take precedence over anonymous mode.** If the client sends an `Authorization: Bearer …` header, the backend treats the request as authenticated and ignores the anonymous session ID. There is no fallback to anonymous when a bearer token is invalid or expired — the request returns `401`.

  A common bug: a user logs in on `/private`, then opens `/public` in the same browser. The persisted bearer is attached to public-route requests and the backend returns the authenticated user's data. Container apps must scrub the `Authorization` header on public routes — see [SDK behaviour](#sdk-and-container-app-behaviour) below.
</Warning>

### Public build, public assets

Once a runtime build is published with the Anonymous role and the app is shared publicly, the build is considered **public**. All assets inside it are reachable anonymously — except UI flows and processes that have not been explicitly opened to the Anonymous role.

Public assets in a public build:

* **Enumerations** — `/rtm/api/runtime/app/{appId}/build/{buildId}/rt/enumeration/...`
* **Substitution tags** — `/rtm/api/runtime/app/{appId}/build/{buildId}/rt/substitutiontag`
* **Media files** — `/rtm/api/runtime/app/{appId}/build/{buildId}/rt/mediafile`
* **Themes** — `/cms/api/wks/{workspaceId}/themes/uuid/{themeId}/platform/{platform}/compiled` (globally unauthenticated)
* **Fonts** — `/cms/api/fonts` (globally unauthenticated)

Restricted assets (require authentication and a role grant):

* UI flows not configured with Anonymous
* Processes not configured with Anonymous
* Chat, task manager, and view-scoped endpoints — see [Restricted endpoints](#restricted-endpoints) below

***

## SDK and container app behaviour

### Renderer initialization

Process and UI flow renderer components decide their mode **at initialization** from the `authToken` parameter:

* `authToken` **present (non-null)** → renderer runs in authenticated mode. All outgoing requests carry the bearer token. If the token expires mid-flow the renderer surfaces `401` errors (existing behaviour).
* `authToken` **absent (null/undefined)** → renderer runs in anonymous mode. The renderer omits the `Authorization` header and uses `X-Fx-Anonymous-Session-Id` instead.

<Warning>
  **The mode is locked at init.** Switching `authToken` from `null` to a value after the renderer has started will not flip it into authenticated mode, and vice versa. If you need both modes in the same container app, mount separate renderer instances on separate routes (e.g. `/public` and `/private`).
</Warning>

### Container apps

A container app that hosts both public and authenticated routes must guarantee that public routes do **not** pass an `Authorization` header to the renderer. The renderer uses an isolated HTTP client at runtime, so whatever the container does for its own pages does not automatically leak in — but if the container reads a token from `localStorage` and supplies it to the renderer, the token-precedence rule above applies and anonymous mode is silently bypassed.

The recommended pattern:

* Public route (e.g. `/public/...`) → mount renderer with `authToken={null}`
* Private route (e.g. `/private/...`) → mount renderer with `authToken={accessToken}`
* Clear any stored bearer when the user navigates from `/private` to `/public`.

### Platform support

| Capability                           | Web (React, Angular)      | iOS                       | Android                   |
| ------------------------------------ | ------------------------- | ------------------------- | ------------------------- |
| Anonymous start of process / UI flow | ✅                         | ✅                         | ✅                         |
| Anonymous session ID handling        | ✅                         | ✅                         | ✅                         |
| File uploads with anonymous session  | ✅                         | ✅                         | ✅                         |
| SSE streams (limited types)          | ✅                         | ✅                         | ✅                         |
| Task manager surfaces                | n/a — restricted          | n/a — restricted          | n/a — restricted          |
| Chat surfaces                        | n/a — restricted in 5.9.0 | n/a — restricted in 5.9.0 | n/a — restricted in 5.9.0 |

***

## What anonymous users can call

Anonymous traffic is allowed on a curated set of runtime endpoints. The full reference is the SDK endpoint table — the summary below is grouped by capability. Endpoints flagged **session ID required** must include `X-Fx-Anonymous-Session-Id`; the backend rejects requests where the session ID does not match the entity it refers to (`403 Anonymous session not found for entity`).

### Allowed

| Capability                                                    | Endpoints                                                                                                                                                                                                                                                                                                           | Session ID                                                         |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Build info                                                    | `/rtm/api/runtime/wks/{wks}/app/{appId}/build/info`<br />`/rtm/api/runtime/process-instance/{piUuid}/build/info`<br />`/rtm/api/runtime/ui-flow-session/{sessionUuid}/build/info`                                                                                                                                   | Required on the last two                                           |
| Process — start                                               | `POST /rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{name}/start`<br />`POST /rtm/api/runtime/app/{appId}/build/{buildId}/process-rdi/{rid}/start`                                                                                                                                                      | Optional on start — issued by BE if missing                        |
| Process — status, data, details, actions, dismiss, subprocess | `GET /api/runtime/process/{piUuid}/status`<br />`GET .../data`, `.../data/{templateConfigId}/context/{ctx}`<br />`GET .../node/{nodeDefId}/context/{ctx}/details`<br />`POST .../token/{tokenUuid}/ui-action/{uiActionUuid}/context/{ctx}/execute`<br />`POST .../ui-action/.../subprocess`<br />`POST .../dismiss` | Required                                                           |
| UI flow — start                                               | `POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flows/{name}`<br />`POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flow-rdi/{rid}`                                                                                                                                                                      | Optional on start                                                  |
| UI flow — status, file upload                                 | `GET /api/runtime/ui-flow-session/{uuid}/status`<br />`POST /api/runtime/wks/{wks}/appId/{appId}/ui-flow/{uuid}/upload`<br />`POST .../upload-multiple`                                                                                                                                                             | Required                                                           |
| Workflow — start from UI flow                                 | `POST /rtm/api/runtime/wks/{wks}/app/{appId}/rdi/{rid}/start-workflow?uiFlowSessionUuid={uuid}`                                                                                                                                                                                                                     | Required. The user must also be authorized for the parent UI flow. |
| Data model paths (gated by Anonymous role on the resource)    | `GET /rtm/api/runtime/process-instance/{piUuid}/data-model-paths`<br />`GET .../app/{appId}/build/{buildId}/process-name/{name}/data-model-paths` (and equivalent for processes by `rdi`, and UI flows by `ui-flow-session`, `ui-flow-name`, `ui-flow-rdi`)                                                         | Required on the process-instance and ui-flow-session forms         |
| CMS — enumerations, substitution tags, media                  | See [Public build, public assets](#public-build-public-assets) above                                                                                                                                                                                                                                                | n/a                                                                |
| Themes, fonts                                                 | Globally unauthenticated                                                                                                                                                                                                                                                                                            | n/a                                                                |
| SSE — process instance                                        | `GET /api/events/process-instance/{piUuid}?offset={offset}`                                                                                                                                                                                                                                                         | Required                                                           |
| SSE — generic, allowed types only                             | `GET /api/events/generic/{id}?type={type}&offset={offset}`<br />**Allowed types:** `UI_FLOW_WORKFLOW_RESPONSE`, `UI_FLOW_FILE_UPLOAD`, `UI_FLOW_FILE_UPLOAD_MULTIPLE`                                                                                                                                               | Required — used to correlate the entity with the session           |
| File uploads (UI flow scope)                                  | `POST /document/internal/wks/{wks}/temp-files/upload`<br />`POST .../upload-multiple`                                                                                                                                                                                                                               | Required                                                           |

### Restricted endpoints

The following are **never** served anonymously, regardless of the public gates:

* **Task manager** — every `/rtm/api/runtime/app/.../view/...` and `/task/api/tasks/...` endpoint
* **Chat** — `/rtm/api/runtime/wks/.../conversations`, chat-workflow start, chat-session upload (postponed past 5.9.0)
* **View-based SSE** — `/api/events/view/{viewId}`
* **Generic SSE other types** — `CHAT_WORKFLOW_RESPONSE`, `CHAT_FILE_UPLOAD`
* **Internal runtime endpoints** — anything under `/rtm/api/runtime-internal/wks/.../app-version/...` (including `process-resource-id/.../start/test` and `start/email-trigger`)
* **Languages** — `/cms/api/languages` is not exposed for anonymous in 5.9.0

***

## Error responses

| Status | Body `detail`                                             | Cause                                                                                                              |
| ------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 403    | `Anonymous access not enabled for this application`       | The app is not publicly shared (General access is **Only invited users and groups**).                              |
| 403    | `Anonymous access not enabled for this build`             | The build does not carry the Anonymous role on the requested resource.                                             |
| 403    | `Anonymous session not found for entity`                  | The `X-Fx-Anonymous-Session-Id` header does not match the session the entity was created with.                     |
| 401    | `Full authentication is required to access this resource` | The endpoint requires authentication and no bearer token was provided.                                             |
| 401    | (any)                                                     | A bearer token was sent but invalid or expired. The backend does **not** fall back to anonymous mode in this case. |

***

## CORS requirements

Two headers must be in the gateway's `Access-Control-Allow-Headers` allow-list and `Access-Control-Expose-Headers` response list:

```yaml theme={"system"}
Access-Control-Allow-Headers:
  - X-Fx-Anonymous-Session-Id
  - Fx-BuildId

Access-Control-Expose-Headers:
  - X-Fx-Anonymous-Session-Id
```

`Fx-BuildId` is required on SSE connections so the backend can route the stream to the correct build when no user identity is present.

The default FlowX `commons-security-lib` CORS configuration includes both headers from 5.9.0. If you override CORS in your deployment, make sure these are preserved.

***

## Limitations (5.9.0)

* **Fire-and-forget sessions** — closing the browser ends the session. No resumption.
* **No task assignment** to anonymous users. Anonymous can start and act on a process they own via the session ID; they cannot be assigned an existing task.
* **Mode is locked at renderer init** — see [Renderer initialization](#renderer-initialization).
* **No anonymous chat** in 5.9.0.
* **No anonymous languages endpoint** (`/cms/api/languages`).
* **Subprocesses** — `data-model-paths` calls for subprocesses are gated by the same session-ID check as the root process instance.
* **Anonymous role cannot be removed or renamed.** It can only be added to or removed from a project's End User Roles.

***

## Related resources

<CardGroup>
  <Card title="Swimlanes" icon="layer-group" href="./swimlanes">
    Configuring swimlane roles, including Anonymous, for process steps.
  </Card>

  <Card title="Business filters" icon="filter" href="./business-filters">
    Other role-driven runtime filtering.
  </Card>

  <Card title="Roles & permissions matrix" icon="table" href="../../../setup-guides/access-management/roles-permissions-matrix">
    Full list of system and end-user roles, with allowed operations.
  </Card>

  <Card title="Web SDK renderer" icon="react" href="../../../sdks/react-renderer">
    `authToken` initialization rules and container-app patterns.
  </Card>
</CardGroup>


# Business filters
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/user-roles-management/business-filters

An optional attribute, from the authorization token, that can be set to restrict access to process instances based on a business specific value (for example, bank branch name).

Business filters provide an additional layer of access control for runtime process instances by restricting access based on business-specific attributes such as bank branch, department, or region.

<Info>
  **Important distinction:** Business filters only apply to **runtime access** (container apps, task manager). They do not affect access in **FlowX Designer**, which is controlled by workspace and project-level permissions.
</Info>

**Use case example**: in a banking app, you might need to ensure that only users from a specific branch can view and interact with process instances initiated from that branch.

## How business filters work

Business filters work in combination with runtime permissions, not as a replacement for them.

### Access control by context

| Context                      | Access controlled by                                     |
| ---------------------------- | -------------------------------------------------------- |
| **FlowX Designer**           | Workspace and project-level permissions only             |
| **Container apps (runtime)** | Runtime permissions AND business filters (both required) |

Business filters add an additional restriction layer but do not bypass existing runtime permissions. Both conditions must be satisfied for a user to access a process instance.

## Prerequisites

Before configuring business filters, ensure you have:

* Access to your identity provider (IdP) configuration
* Organization administrator role to manage user attributes
* Understanding of your business access requirements (for example, which users should access which process instances)

## Configuration

Follow these steps to implement business filters in your app.

### 1. Configure the identity provider mapper

Configure a mapper in your identity management platform to add the business filter attribute to the authorization token as a claim. This mapper creates the connection between user attributes and the token claim that gets evaluated at runtime.

<Warning>
  The business filter attribute must always be available on the token under the same key. Inconsistent mapper configuration can cause access control issues in production environments.
</Warning>

<Card title="Identity provider mapper configuration" href="/5.9/setup-guides/access-management/configuring-an-iam-solution#user-attribute-mapper" icon="key">
  View detailed instructions for configuring the user attribute mapper
</Card>

After configuration, the `businessFilter` attribute becomes visible at the user level:

<Frame>
  ![Business filter attribute displayed at user level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/bsF.png)
</Frame>

### 2. Assign business filter values to users

Assign business filter values to users through one of the following methods:

* **Identity provider**: Directly in the user profile settings
* **FlowX Designer**: Through the user management interface

<Warning>
  **Important:** Business filter values must be set directly on user attributes in your identity provider, not only inherited from groups.

  When assigning business filters in FlowX Designer, you must use the `businessFilter` key.

  <Frame>
    ![Assigning business filter values in Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/bsF1.png)
  </Frame>
</Warning>

Users can have multiple business filter values assigned. For example: `["branch_01", "branch_02"]`

<Info>
  **Technical note:** While group-level attributes can propagate to the JWT via mappers, Task Manager uses a different mechanism to filter assignable users. It queries user attributes directly from the identity provider when listing users for task assignment. This means business filters must exist as direct user attributes, not only as group memberships.
</Info>

### 3. Set business filters in process definition

Add a [**business rule action**](../../building-blocks/actions/business-rule-action/business-rule-action) in your process definition to store the business filter values in the process parameters.

**Syntax:**

Single value:

```javascript theme={"system"}
output.put("task", {"businessFilters": ["branch_01"]});
```

Multiple values:

```javascript theme={"system"}
output.put("task", {"businessFilters": ["branch_01", "branch_02"]});
```

<Warning>
  **Important:** When configuring the business rule action node that sets `task.businessFilters`, you must also enable the **Update Task Manager** toggle in the node configuration. This ensures that the business filter values are properly propagated to Task Manager.
</Warning>

<Info>
  **Best practice:** Set business filters early in the process flow, typically on an automatic action at the start of the process.
</Info>

## Runtime behavior

Once business filters are configured on a process instance, access restrictions apply based on the context:

We have a process instance with the business filter value `"branch_01"` (added in the process definition) and a user with the business filter value `"branch_01"`. The second user does not have the business filter value.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rt_pi_bf.png)
</Frame>

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rt_bf.png)
</Frame>

<Info>
  Business filters are applied to the process instance at runtime.

  * in the left screen there is a user with the business filter value `"branch_01"` (the process instance is visible to this user)
  * in the right screen there is a user without the business filter value (the process instance is not visible to this user)
</Info>

### Task manager

Only users with matching business filter values can view and interact with tasks from the process instance.

<Frame>
  ![Task manager business filter example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/tm_bf.png)
</Frame>

When assigning or reassigning tasks to other users, the list of assignable users is filtered based on business filters. The system queries user attributes directly from the identity provider to determine which users can be assigned to a task.

<Info>
  Business filter checks apply to the tasks themselves. Custom views remain controlled by Designer permissions.
</Info>

### Container apps

Only users with matching business filter values can execute READ operations on the process instance, such as:

* GET status
* GET details

### Designer

Business filters do not apply in FlowX Designer. All users with appropriate project permissions can view the process instance regardless of their business filter values.

## Example scenario

This example demonstrates how to restrict access to process instances based on bank branch affiliation.

### Setup

**Step 1**: configure the identity provider mapper for the `businessFilter` attribute.

**Step 2**: assign business filter values to users:

* User A: `"branch_downtown"`
* User B: No business filter assigned

**Step 3**: add a business rule in your process definition:

```javascript theme={"system"}
output.put("task", {"businessFilters": ["branch_downtown"]});
```

### Expected behavior

When a process instance runs with this configuration:

| User   | Business filter     | Runtime access                                  | Designer access                           |
| ------ | ------------------- | ----------------------------------------------- | ----------------------------------------- |
| User A | `"branch_downtown"` | ✓ Can access                                    | ✓ Can access (if has project permissions) |
| User B | None                | ✗ Cannot access (even with runtime permissions) | ✓ Can access (if has project permissions) |

This demonstrates that:

* Business filters enforce runtime restrictions
* Designer access remains independent of business filters
* Runtime permissions alone are insufficient without matching business filter values


# Swimlanes
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/user-roles-management/swimlanes

Swimlanes provide a way of grouping process nodes by process participants.

Using swimlanes we can make sure only certain user roles have access to certain process nodes.

In certain scenarios, it is necessary to restrict access to specific process [**nodes**](../../building-blocks/node/) based on user roles. This can be achieved by organizing nodes into different swimlanes.

Each swimlane can be configured to grant access only to users with specific runtime roles. Roles are defined at the organization level and listed on each project version. Which user or end-user group holds a role on a given solution is configured from the Share modal on the Solutions page — see [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization) for the full model (5.8.0+). Up to 5.7.0, the chosen identity provider platform was the source of truth for runtime roles.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/multiple_swimlanes.png)

Depending on the type of node added within a swimlane, only users with the corresponding swimlane roles will have the ability to initiate process instances, view process instances, and perform actions on them.

[Scopes and roles for managing processes](../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/swimlanes_permissions.gif)

When creating a new process definition, a default swimlane will automatically be added.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/swimlanes_default.gif)

As the token moves from one node to the next, it may transition between swimlanes. If a user interacting with the process instance no longer has access to the new swimlane, they will observe the process in read-only mode and will be unable to interact with it until the token returns to a swimlane they have access to.

Users will receive notifications when they can no longer interact with the process or when they can resume actions on it.

***

## Related resources

<CardGroup>
  <Card title="Permission-based expressions" icon="shield-halved" href="../../building-blocks/process/permission-based-expressions">
    Control UI element visibility and interaction based on user roles
  </Card>

  <Card title="Access roles configuration" icon="user-shield" href="/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes">
    Set up scopes and roles for managing processes
  </Card>

  <Card title="From Zero to Build course" icon="graduation-cap" href="https://academy.flowx.ai/explore/5from-zero-build-onboarding-project">
    End-to-end project build course covering swimlanes, permissions, and all major platform features
  </Card>
</CardGroup>


# Context Retrieval
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/context-retrieval

Query Knowledge Bases and retrieve relevant chunks using RAG search without calling an LLM.

## Overview

The **Context Retrieval** node is a specialized [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) workflow node that performs RAG (Retrieval-Augmented Generation) searches against a Knowledge Base. Unlike the [Custom Agent](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) node, Context Retrieval does **not** call an LLM — it retrieves and returns matching chunks directly, giving you full control over how the results are processed downstream.

<Frame>
  ![Context Retrieval node configuration with Source, User Query, Search Type, and relevance settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
</Frame>

<Tip>
  Use Context Retrieval when you want to separate the retrieval step from the generation step. This lets you inspect, filter, or transform retrieved chunks before passing them to an AI node for response generation.
</Tip>

***

## When to use Context Retrieval vs Custom Agent

| Scenario                                                                      | Recommended node                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------------------- |
| You need the AI to reason about retrieved information and generate a response | **Custom Agent** with Knowledge Base enabled          |
| You want raw chunks to process, filter, or route in your workflow             | **Context Retrieval**                                 |
| You need to combine chunks from multiple Knowledge Bases                      | **Context Retrieval** (one per KB) + downstream merge |
| You want a simple question-answer flow with RAG                               | **Custom Agent** with Knowledge Base enabled          |

***

## Configuration

### Knowledge Base

<ParamField type="select">
  Select one or more Knowledge Base resource references to query.
</ParamField>

### Source

<ParamField type="enum">
  The source to query.

  **Options:**

  * **Knowledge Base** — Search the selected Knowledge Base (default)
  * **Memory** — Search [conversation memory](/5.9/ai-platform/conversational-workflows#session-memory)

  The **Memory** option is only available in [conversational workflows](/5.9/ai-platform/conversational-workflows).

  **Default:** **Knowledge Base**
</ParamField>

### Settings

The settings below are available inside the **Settings** expander on the node configuration panel.

#### Search type

<ParamField type="enum">
  The strategy used for retrieving context from the Knowledge Base.

  **Options:**

  * `Hybrid` — Combines semantic and keyword search for balanced results (default)
  * `Semantic` — Uses vector similarity for meaning-based search
  * `Keywords` — Uses traditional keyword matching

  **Default:** `HYBRID`

  <Tip>
    When **Keywords** is selected, the **Min Relevance Score** slider is hidden because keyword search does not produce a relevance score.
  </Tip>
</ParamField>

#### Query parameters

<ParamField type="number">
  Maximum number of relevant chunks to return. Configurable from 1 to 10.

  **Default:** `4`
</ParamField>

<ParamField type="number">
  Minimum relevance score threshold, expressed as a percentage (0–100). Only chunks with a relevance score above this threshold are returned. Not available when search type is set to **Keywords**.

  **Default:** `50`
</ParamField>

#### Metadata filters

<ParamField type="button">
  Opens a query builder modal where you compose conditions as **field / operator / value** triples. Operators depend on the metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with **AND** or **OR**.

  To filter by store, add a condition on the system metadata key `source`.

  <Info>
    Typed operators and AND/OR grouping are supported. See [Filtering by metadata](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#filtering-by-metadata) for the full operator list.
  </Info>
</ParamField>

<ParamField type="boolean">
  Toggle to turn on advanced metadata filter expressions for more complex filtering logic. When turned on, a JSON expression field becomes available for defining property-based filters.

  **Default:** `false`
</ParamField>

#### Re-ranking

<ParamField type="boolean">
  When turned on, applies a re-ranking model to the retrieved chunks, reordering them by relevance to the query. This can improve result quality at the cost of slightly higher latency.

  **Default:** `false`
</ParamField>

***

## User Query

<ParamField type="string">
  The query text sent to the Knowledge Base. Supports `${}` placeholder syntax for dynamic values from workflow input and configuration parameters.

  **Example:**

  ```
  ${userMessage}
  ```

  Both runtime input variables and configuration parameters are available for placeholder resolution.
</ParamField>

***

## Response Key

<ParamField type="string">
  Key under which the retrieved chunks are stored in the workflow data, so downstream nodes can reference them.

  **Default:** `responseKey`
</ParamField>

***

## Output format

The Context Retrieval node returns an array of chunk objects. Each chunk contains:

| Field              | Type     | Description                                                                                                                                      |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **chunkContent**   | `string` | The text content of the retrieved chunk                                                                                                          |
| **chunkMetadata**  | `object` | Metadata associated with the chunk (key-value pairs)                                                                                             |
| **relevanceScore** | `number` | Similarity score between the query and the chunk (0–1)                                                                                           |
| **searchType**     | `string` | Search strategy that returned this chunk. One of `HYBRID`, `SEMANTIC`, or `KEYWORD`. Only emitted when the RAG service returns a non-null value. |
| **contentSource**  | `string` | The name of the store the chunk belongs to (field name preserved for API compatibility)                                                          |

### Example output

```json theme={"system"}
[
  {
    "chunkContent": "The onboarding process requires identity verification...",
    "chunkMetadata": {
      "source": "onboarding-guide.pdf",
      "page": "3"
    },
    "relevanceScore": 0.92,
    "contentSource": "Product Documentation"
  },
  {
    "chunkContent": "KYC checks must be completed within 48 hours...",
    "chunkMetadata": {
      "source": "compliance-policy.pdf",
      "page": "12"
    },
    "relevanceScore": 0.85,
    "contentSource": "Compliance Policies"
  }
]
```

***

## Error handling

If the Context Retrieval node fails, the workflow produces a `WORKFLOW_NODE_CONTEXT_RETRIEVAL_ERROR` error. Common causes include:

<AccordionGroup>
  <Accordion title="Knowledge Base not found" icon="database">
    The referenced Knowledge Base does not exist or is not accessible.

    **Solution:** Verify the Knowledge Base exists in your project or dependencies and that you have the required permissions.
  </Accordion>

  <Accordion title="Invalid query" icon="message-exclamation">
    The operation prompt resolved to an empty or invalid query.

    **Solution:** Check that the `${}` placeholders in your operation prompt reference valid input or config variables.
  </Accordion>

  <Accordion title="Timeout" icon="clock">
    The RAG search exceeded the configured timeout.

    **Solution:** The default timeout is 600 seconds (`flowx.ai-service.nodeRunnerTimeoutSeconds`). Consider simplifying your query or reducing the `topK` value.
  </Accordion>
</AccordionGroup>

***

## Best practices

<Tip>
  **Optimizing Context Retrieval:**

  * Start with **Hybrid** search type for the best balance of precision and recall
  * Use **Semantic** when your queries are natural-language questions; use **Keywords** for exact-match lookups
  * The default minimum relevance threshold (50%) is a good starting point — increase it to filter out lower-quality matches
  * Turn on **Use Re-Rank** when result quality is more important than latency
  * Use metadata filters to narrow results to specific stores (via the `source` key) or metadata values
  * Keep **Max Number of Chunks** reasonable (3–10) to avoid overwhelming downstream nodes with too much context
</Tip>

<Tip>
  **Building RAG pipelines:**

  * Chain Context Retrieval → Script Node → Custom Agent to build custom RAG flows with intermediate processing
  * Use the `relevanceScore` field to implement your own relevance filtering logic in a Script node
  * Combine results from multiple Context Retrieval nodes (querying different KBs) using a Script node before passing to generation
</Tip>

***

## Related resources

<CardGroup>
  <Card title="Knowledge Base overview" icon="book" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
    Create and manage Knowledge Bases
  </Card>

  <Card title="Using Knowledge Base in workflows" icon="magnifying-glass" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows">
    Query Knowledge Bases with Custom Agent nodes
  </Card>

  <Card title="Custom Agent node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
    AI agents with MCP tools and Knowledge Base access
  </Card>

  <Card title="Integration Designer" icon="diagram-project" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Build and manage integration workflows
  </Card>
</CardGroup>


# Extract Data from File
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/extract-data-from-file

Configure the Extract Data from File AI node to extract text and data from documents and images using LLM, OCR, or text parsing strategies.

## Overview

The **Extract Data from File** node extracts text and structured data from documents and images within Agent Builder workflows. It supports multiple extraction strategies so you can balance accuracy, speed, and cost based on your document types.

### Supported file formats

| Category  | Formats                          |
| --------- | -------------------------------- |
| Documents | PDF, DOCX, XLSX, XLS, XLSM, PPTX |
| Images    | JPG, PNG, TIFF                   |

<Info>
  Image files are automatically converted to PDF before processing. This conversion is handled by the Document Parser service.
</Info>

***

## Configuration

To add the node to an Agent Builder workflow:

<Steps>
  <Step title="Open your workflow">
    Open your workflow in **Agent Builder**.
  </Step>

  <Step title="Add the node">
    Add an **Extract Data from File** node from the **Document Operations** category.
  </Step>

  <Step title="Configure extraction settings">
    Configure the extraction settings described below.
  </Step>
</Steps>

<Frame>
  ![Extract Data from File node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/extract_data_config_panel.png)
</Frame>

### Document source

<ParamField type="select">
  The source system for the document. Select **Document Plugin** to use files stored in the FlowX Documents Plugin.

  **Default:** `Document Plugin`
</ParamField>

### Use test file

<ParamField type="boolean">
  Toggle **ON** to use a test file during workflow configuration and testing, without requiring a live file path from process data.

  **Default:** OFF
</ParamField>

### File path

<ParamField type="string">
  The path to the input file to process. This can reference a file stored in the Documents Plugin.

  <Tip>
    When **Use Test File** is turned off, map this field to a process variable or workflow data key that contains the file path at runtime.
  </Tip>
</ParamField>

***

### Response key

<ParamField type="string">
  The key where the extraction results are stored in the workflow data.

  **Example:** `extractedData`
</ParamField>

***

### Extraction method

<ParamField type="select">
  Select the method used to extract content from the file. Each method has different accuracy, speed, and cost characteristics.

  | Method           | Best for                                                     | Speed  | Cost   | Accuracy   |
  | ---------------- | ------------------------------------------------------------ | ------ | ------ | ---------- |
  | **Automatic**    | Mixed document sets where you don't know the format up front | Varies | Varies | Varies     |
  | **LLM Model**    | Complex layouts, handwritten text, mixed content             | Slow   | High   | High       |
  | **OCR Engine**   | Scanned documents, image-heavy files                         | Medium | Medium | Medium     |
  | **Text Parsing** | Clean digital PDFs with selectable text                      | Fast   | Free   | Low–Medium |
</ParamField>

<Tabs>
  <Tab title="Automatic">
    The platform selects the best extraction method for each document automatically — *"AI will choose the best method for each document."* Use it for mixed document sets where the format varies and you don't want to pick a strategy per file.
  </Tab>

  <Tab title="LLM Model">
    Uses AI vision models (such as GPT-4o) to analyze document content. This strategy provides the highest accuracy and can handle:

    * Complex page layouts with multiple columns
    * Handwritten text and annotations
    * Mixed content (text, tables, images on the same page)
    * Documents with non-standard formatting

    <Warning>
      LLM Model is the most expensive strategy due to AI API calls per page. Use it when accuracy is critical and the document structure is complex.
    </Warning>
  </Tab>

  <Tab title="OCR Engine">
    Uses Optical Character Recognition engines (Tesseract, RapidOCR, or EasyOCR) to extract text from images and scanned documents. Best for:

    * Scanned paper documents
    * Photographed documents
    * Image-heavy files where text is embedded in images

    <Info>
      The OCR engine used is configured at the service level. See the [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) for engine selection.
    </Info>
  </Tab>

  <Tab title="Text Parsing">
    Extracts text directly from the document file without AI or OCR processing. Best for:

    * Clean digital PDFs with selectable text
    * Documents generated by software (not scanned)
    * High-volume processing where speed matters

    <Tip>
      Text Parsing is the fastest and most cost-effective option. Use it as a first pass and fall back to OCR or LLM for documents with low extraction quality.
    </Tip>
  </Tab>
</Tabs>

***

### Image extraction options

When using **LLM Model** or **OCR Engine**, you can configure how images found within the document are handled.

<ParamField type="select">
  Select how images embedded in the document should be processed.

  | Option                | Description                            | When to use                                                               |
  | --------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
  | **Image Description** | Generates a text description of images | When you need to understand what images depict (charts, photos, diagrams) |
  | **Image Contents**    | Extracts text and data from images     | When images contain text, tables, or data you need to capture             |

  <Info>
    LLM Model supports both Image Description and Image Contents. OCR Engine supports only Image Contents.
  </Info>
</ParamField>

<Info>
  Image extraction options are not available when using the Text Parsing strategy, since Text Parsing only handles selectable text content.
</Info>

***

### Signature detection

<ParamField type="boolean">
  Turn on detection of signatures within the document.

  **Default:** OFF

  When enabled, the node identifies areas of the document that contain signatures and includes their locations in the extraction results.
</ParamField>

<Info>
  Signature detection is only available when using **LLM Model** or **OCR Engine** strategies. It is not available for Text Parsing.
</Info>

### Personal Information Guard

<ParamField type="boolean">
  Detects and replaces personal data in messages before they reach the model. A system instruction is automatically added so the agent handles redacted content naturally.

  **Default:** OFF

  When turned on, the following sub-options become available:

  * **Detection Algorithm Sensitivity** — One of **Strict**, **Balanced** (default), **Relaxed**, or **Custom**. Controls how aggressively the detector flags potential matches.
  * **Detection Target** — Check **Node Input**, **Node Output**, or both to choose which payloads are scanned.
  * **Personal Info Types** — Opens the **Customize Entities** modal, the picker for which of the 24 supported entity types should be detected. All 24 are enabled by default. Entities are grouped into **Universal** and **Regional** (per-locale) sets.

  <AccordionGroup>
    <Accordion title="Supported entity types (24)" icon="shield-halved">
      **Universal (8)**

      `EMAIL`, `PHONE`, `CREDIT_CARD`, `IBAN`, `MAC_ADDRESS`, `CRYPTO_WALLET`, `PERSON`, `ADDRESS`

      **Regional — EN (6)**

      `SSN`, `US_PASSPORT`, `US_BANK_ACCOUNT`, `US_ITIN`, `UK_NHS`, `EU_VAT_ID`

      **Regional — RO (10)**

      `CNP`, `CUI`, `RO_IBAN`, `RO_PHONE`, `RO_PASSPORT`, `RO_ID_CARD`, `LICENSE_PLATE`, `HEALTH_CARD`, `POSTAL_CODE`, `LANDLINE`
    </Accordion>
  </AccordionGroup>
</ParamField>

***

## Examples

<AccordionGroup>
  <Accordion title="Processing a scanned invoice" icon="file-invoice">
    **Scenario:** Extract line items and totals from a scanned paper invoice.

    **Configuration:**

    * **Extraction Method:** OCR Engine
    * **Image Extraction:** Image Contents
    * **Detect Signatures:** ON (to capture the approval signature)

    The OCR engine processes the scanned image, extracts text from both the document body and any embedded images (such as company logos with text), and identifies signature areas.
  </Accordion>

  <Accordion title="Analyzing a contract with charts" icon="file-contract">
    **Scenario:** Extract text and understand visual elements from a contract that includes charts and diagrams.

    **Configuration:**

    * **Extraction Method:** LLM Model
    * **Image Extraction:** Image Description
    * **Detect Signatures:** OFF

    The LLM analyzes each page, extracts the contract text, and generates descriptions of charts and diagrams (for example, "Bar chart showing quarterly revenue growth from Q1 to Q4 2025").
  </Accordion>

  <Accordion title="Extracting text from a clean PDF" icon="file-pdf">
    **Scenario:** Extract text from a digitally generated report PDF.

    **Configuration:**

    * **Extraction Method:** Text Parsing
    * **Image Extraction:** N/A (not available for Text Parsing)
    * **Detect Signatures:** N/A (not available for Text Parsing)

    Text Parsing directly extracts the selectable text from the PDF with no AI or OCR processing, making it the fastest and lowest-cost option.
  </Accordion>
</AccordionGroup>

***

## Best practices

<CardGroup>
  <Card title="Start with Text Parsing" icon="bolt">
    For digital PDFs, try Text Parsing first. Only use OCR or LLM if the results are insufficient.
  </Card>

  <Card title="Match strategy to document type" icon="bullseye">
    Use OCR for scanned documents, LLM for complex layouts, and Text Parsing for clean digital files.
  </Card>

  <Card title="Consider cost at scale" icon="coins">
    LLM processing costs increase linearly with page count. For high-volume workloads, use Text Parsing or OCR where possible.
  </Card>

  <Card title="Turn off unused features" icon="toggle-off">
    Turn off signature detection and image extraction when not needed to reduce processing time and cost.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Document Parser setup" icon="server" href="/5.9/setup-guides/document-parser-setup">
    Configure the Document Parser service, parsing engines, and deployment sizing
  </Card>

  <Card title="AI node types" icon="diagram-project" href="./node-types">
    Overview of all AI node types available in Agent Builder
  </Card>

  <Card title="Agent Builder overview" icon="robot" href="./overview">
    Get started with Agent Builder workflows
  </Card>

  <Card title="Use cases" icon="lightbulb" href="./use-cases">
    See real-world Agent Builder workflow examples
  </Card>
</CardGroup>


# Intent Classification
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/intent-classification

Classify user messages and route workflows to different branches using AI-powered intent detection.

## Overview

The **Intent Classification** node is a specialized [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) workflow node that combines AI-powered message classification with workflow branching in a single node. It analyzes a user message, classifies it into one of your defined intents using an LLM, and automatically routes the workflow to the matching branch — replacing the previous two-node pattern (TEXT\_UNDERSTANDING + Condition).

<Frame>
  ![Intent Classification Agent node with intents list and the If No Intent Matches default branch](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/if_no_intent_matches.png)
</Frame>

<Tip>
  The Intent Classification node is available in Integration Designer workflows alongside other node types like REST Endpoint, Script, Condition, and Custom Agent. For BPMN process workflows, use the [Start Integration Workflow](/5.9/docs/building-blocks/actions/start-integration-workflow) action to invoke workflows that contain Intent Classification nodes.
</Tip>

<CardGroup>
  <Card title="AI + routing in one node" icon="code-merge">
    Combines LLM classification and conditional branching — no separate Condition node needed
  </Card>

  <Card title="Natural language conditions" icon="message">
    Define intents as plain-text descriptions instead of code expressions
  </Card>

  <Card title="Conversation memory" icon="brain">
    Optionally use past conversation context for more accurate classification
  </Card>

  <Card title="Built-in fallback" icon="shield">
    Automatic "If No Intent Matches" branch handles unrecognized inputs
  </Card>
</CardGroup>

### How it compares to the pattern approach

| Aspect              | Pattern (TEXT\_UNDERSTANDING + Condition) | Intent Classification node     |
| ------------------- | ----------------------------------------- | ------------------------------ |
| **Nodes required**  | 2 (classify, then route)                  | 1 (classify and route)         |
| **Conditions**      | Python/JavaScript expressions             | Natural language descriptions  |
| **Max branches**    | Unlimited                                 | 10 intents + fallback          |
| **Response schema** | Manual JSON schema                        | Automatic (handled internally) |
| **Rationale**       | Must be added to prompt manually          | Built-in toggle                |

***

## Configuration

<Steps>
  <Step title="Open your workflow">
    Open your workflow in **Integration Designer**.
  </Step>

  <Step title="Add the node">
    Add an **Intent Classification** node from the **AI Agents** category in the left panel.
  </Step>

  <Step title="Configure the user message">
    Set the **User message** field to the input text that should be classified. Use `${}` syntax to reference workflow data keys.
  </Step>

  <Step title="Define intents">
    Add intent descriptions — each intent becomes a separate output branch on the node.
  </Step>

  <Step title="Connect output branches">
    Connect each intent branch and the fallback branch to downstream nodes in your workflow.
  </Step>
</Steps>

***

### Personal Information Guard

<ParamField type="boolean">
  Detects and replaces personal data in messages before they reach the model. A system instruction is automatically added so the agent handles redacted content naturally.

  **Default:** OFF

  When turned on, the following sub-options become available:

  * **Detection Algorithm Sensitivity** — One of **Strict**, **Balanced** (default), **Relaxed**, or **Custom**. Controls how aggressively the detector flags potential matches.
  * **Detection Target** — Check **Node Input**, **Node Output**, or both to choose which payloads are scanned.
  * **Personal Info Types** — Opens the **Customize Entities** modal, the picker for which of the 24 supported entity types (Universal + Regional EN + Regional RO) should be detected. All 24 are enabled by default. See the [Extract Data from File](./extract-data-from-file#personal-information-guard) reference for the full entity list.
</ParamField>

***

### User Message

<ParamField type="string">
  The text input to classify. Use `${}` syntax to reference workflow data keys.

  **Example:** `${userMessage}`

  <Tip>
    Reference a workflow data key that contains the user's message rather than hardcoding text. This allows the node to classify different messages at runtime.
  </Tip>
</ParamField>

***

### Use Memory

<ParamField type="boolean">
  When turned on, the node sends the session ID to the AI platform and appends conversation history to the LLM call. This provides context from past messages for more accurate classification. See [Memory Capabilities](/5.9/ai-platform/agent-builder/memory-capabilities) for details on how memory retrieval and summarization work.

  **Default:** OFF

  <Tip>
    Turn on memory when classifying messages in multi-turn conversations where context matters — for example, distinguishing "yes" (confirming a previous offer) from "yes" (answering a question).
  </Tip>
</ParamField>

***

### Intents

<ParamField type="array">
  A list of intent descriptions that define the classification categories. Each intent becomes an output branch on the node.

  * **Minimum:** 1 intent + fallback
  * **Maximum:** 10 intents + fallback
  * Each intent description can be up to 3 lines of text
  * The **If No Intent Matches** fallback branch is always present and cannot be removed

  **Example intents:**

  | Intent   | Description                                                             |
  | -------- | ----------------------------------------------------------------------- |
  | Intent 1 | The user is asking about product features, pricing, or availability     |
  | Intent 2 | The user wants to update their personal information or submit documents |
  | Intent 3 | The user is greeting or making small talk                               |
  | Fallback | If No Intent Matches                                                    |

  <Info>
    For best accuracy, classify up to 10 intents per node. If you need more intents, chain multiple Intent Classification nodes to narrow down in stages.
  </Info>
</ParamField>

***

### Response key

<ParamField type="string">
  The key where the classification result is stored in the workflow data.

  **Example:** `classificationResult`
</ParamField>

***

### Include Reason for Selection

<ParamField type="boolean">
  When turned on, the agent includes a rationale explaining why it chose this intent in its response.

  **Default:** OFF

  <Tip>
    Turn on rationale during development and testing to understand classification decisions. You can turn it off in production to reduce response size.
  </Tip>
</ParamField>

***

## Output

The node stores its classification result under the configured **Response key** in the workflow data. The output contains:

| Field             | Type   | Description                                                                                     |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `selected_intent` | string | The description text of the matched intent                                                      |
| `selected_branch` | number | The branch number (1–11) corresponding to the matched intent                                    |
| `rationale`       | string | Explanation of why the LLM chose this intent (only when **Include Reason for Selection** is ON) |

**Example output:**

```json theme={"system"}
{
  "selected_intent": "The user is asking about product features, pricing, or availability",
  "selected_branch": 1,
  "rationale": "The user asked 'How much does the premium plan cost?' which is a direct inquiry about pricing."
}
```

### Workflow routing

After classification, the node routes the workflow token to the matching branch:

* **Intent branches** — the workflow continues along the branch whose intent description matched the user message
* **If No Intent Matches** — the fallback branch activates when the LLM response doesn't match any defined intent

This routing works like a Condition (Fork) node, but conditions are evaluated by the LLM using natural language instead of code expressions.

***

## Examples

<AccordionGroup>
  <Accordion title="Customer support routing" icon="headset">
    **Scenario:** Route customer messages to specialized support handlers.

    **Intents:**

    1. The customer is reporting a technical issue or bug
    2. The customer is asking about billing, payments, or invoices
    3. The customer wants to cancel or modify their subscription
    4. The customer is asking a general question about the product

    **Fallback:** Routes to a human agent handoff workflow.

    Each branch connects to a specialized handler — for example, the billing branch triggers a workflow that looks up the customer's invoice history, while the technical issue branch creates a support ticket.
  </Accordion>

  <Accordion title="Banking chatbot" icon="building-columns">
    **Scenario:** Classify banking customer requests in a conversational workflow.

    **Intents:**

    1. The user wants to check their account balance or transaction history
    2. The user wants to transfer money or make a payment
    3. The user is asking about loan or mortgage options
    4. The user is greeting or making small talk

    **Configuration:**

    * **Use memory:** ON (to understand context in multi-turn conversations)
    * **Include Reason for Selection:** OFF (production deployment)

    The balance branch queries the account API, the transfer branch starts the payment workflow, and the loan branch triggers a knowledge base lookup.
  </Accordion>

  <Accordion title="Email triage pipeline" icon="envelope">
    **Scenario:** Classify incoming emails and route to appropriate processing.

    **Intents:**

    1. The message is a complaint or escalation requiring urgent attention
    2. The message is a new business inquiry or sales lead
    3. The message is a support request with a reference to an existing ticket
    4. The message is informational (newsletter reply, out-of-office, automated notification)

    **Fallback:** Routes to a manual review queue.

    **Configuration:**

    * **Use memory:** OFF (each email is independent)
    * **Include Reason for Selection:** ON (for audit trail)
  </Accordion>
</AccordionGroup>

***

## Best practices

<CardGroup>
  <Card title="Write specific intent descriptions" icon="pen">
    Describe each intent clearly and distinctly. Vague or overlapping descriptions reduce classification accuracy.
  </Card>

  <Card title="Chain nodes for complex taxonomies" icon="link">
    For more than 10 categories, use a first node to classify into broad groups, then a second node to classify within each group.
  </Card>

  <Card title="Always handle the fallback" icon="shield-check">
    Connect the fallback branch to meaningful handling — a clarification prompt, a human handoff, or a default response.
  </Card>

  <Card title="Use rationale for debugging" icon="bug">
    Turn on Include Reason for Selection during development to understand why the LLM routes to unexpected branches.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Integration Designer" icon="sitemap" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Learn about Integration Designer workflows and all available node types
  </Card>

  <Card title="AI node types" icon="diagram-project" href="./node-types">
    Overview of all AI node types in Agent Builder
  </Card>

  <Card title="Intent classification pattern" icon="signs-post" href="../patterns/intent-classification-routing">
    Alternative approach using TEXT\_UNDERSTANDING + Condition nodes
  </Card>

  <Card title="Conversational workflows" icon="messages" href="../conversational-workflows">
    Multi-turn chat with session memory
  </Card>

  <Card title="Custom Agent node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
    AI agents with MCP tools in Integration Designer workflows
  </Card>

  <Card title="Conversational workflows" icon="comments" href="../conversational-workflows">
    Build multi-turn chat experiences with intent routing
  </Card>
</CardGroup>


# Memory capabilities
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/memory-capabilities

Persist conversation context across messages with automatic session memory retrieval and summarization.

## Overview

Session memory allows AI nodes in conversational workflows to access previous messages from the current conversation. When enabled, FlowX automatically retrieves conversation history and injects it into the LLM's context — giving the AI agent awareness of what was discussed earlier in the session.

Memory is **per-session** (identified by Chat Session ID) and managed entirely by FlowX. You don't need to build any memory retrieval logic — just toggle it on per node.

<CardGroup>
  <Card title="Automatic retrieval" icon="clock-rotate-left">
    Latest 3 message pairs + summary of earlier exchanges retrieved on each message
  </Card>

  <Card title="Smart summarization" icon="compress">
    Older conversation history is automatically summarized to fit within context limits
  </Card>

  <Card title="Per-node control" icon="toggle-on">
    Turn on memory per Custom Agent or Intent Classification node with the **Use Memory** toggle
  </Card>

  <Card title="Memory tab in console" icon="terminal">
    View retrieved memory (raw turns + summary) in the workflow console log
  </Card>
</CardGroup>

***

## How memory works

<Steps>
  <Step title="User sends a message">
    The Chat component sends the message + `chatSessionId` to the Chat Driven workflow.
  </Step>

  <Step title="Memory retrieval">
    The Start node retrieves conversation history for the session: the latest 3 user/agent message pairs in full, plus a summary of all earlier exchanges.
  </Step>

  <Step title="Context injection">
    For each node with **Use Memory** enabled, the retrieved history is appended to the LLM system prompt, giving the AI agent context from prior turns.
  </Step>

  <Step title="Response and storage">
    After the AI generates a response, the system stores both the user message and the agent response, updating the session memory for the next turn.
  </Step>

  <Step title="Summary update">
    When the conversation exceeds 3 turns, older messages are automatically summarized. The summary is regenerated on each new message beyond the threshold.
  </Step>
</Steps>

***

## Memory structure

The memory injected into the LLM prompt follows this structure:

```
user: [message content]
agent: [response content]
user: [message content]
agent: [response content]
user: [message content]
agent: [response content]
Summary of previous replies: [generated summary]
```

* **Recent turns** — The latest 3 user/agent message pairs are included in full
* **Summary** — A compressed summary of all conversation history before the last 3 turns

<Tip>
  Only user messages and agent responses are included in memory. Internal workflow data, routing decisions, and intermediate node outputs are not part of the memory.
</Tip>

***

## Enabling memory

<Frame>
  ![Custom Agent node with Use Memory toggle enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/custom_agent_use_memory.png)
</Frame>

Memory is controlled per node using the **Use Memory** toggle. It's available on:

* **Custom Agent** nodes — for context-aware AI responses
* **Intent Classification** nodes — for more accurate classification using conversation history

**Default:** OFF

When enabled, the node sends the `chatSessionId` to the AI platform, which retrieves and attaches the conversation history to the LLM call.

<Warning>
  Memory is only available in **Chat Driven** workflows. The toggle does not appear on nodes in Output Focused workflows.
</Warning>

***

## Summarization

When a conversation exceeds 3 message turns, FlowX automatically summarizes the older messages using an LLM call. The summarization process:

1. Collects all messages older than the most recent 3 turns
2. Sends them to the LLM with a context extraction prompt
3. Stores the resulting summary for future retrieval
4. The summary is regenerated on each new message to incorporate the latest context

The summarization prompt instructs the LLM to extract the most important and relevant context from the conversation history, focusing on information needed to maintain coherent dialogue.

<Info>
  Summarization happens automatically — there is no configuration needed. The summary prefix `## Previous conversation summary:` is prepended to the summary text in the prompt.
</Info>

***

## Debugging memory in the console

<Frame>
  ![Memory tab in the workflow console showing conversation summary and message history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
</Frame>

The workflow console log includes a **Memory** tab that shows exactly what memory was sent to the LLM for each workflow run.

| Level                 | Tab        | Content                                               |
| --------------------- | ---------- | ----------------------------------------------------- |
| **Workflow**          | Memory tab | Full conversation history and summary sent to the LLM |
| **Workflow**          | Input tab  | User Message and Chat Session ID in JSON format       |
| **Workflow**          | Output tab | Chat response as text                                 |
| **Custom Agent node** | Output tab | Node response as text                                 |

### Memory use summary

When an AI node with **Use Memory** enabled completes, the console displays the `memoryUseSummary` — a snapshot of the conversation context that was available to the LLM. This includes:

* **summary** — the auto-generated summary of earlier conversation history
* **chatMessages** — the most recent message pairs (up to 3, excluding the current message) with their `messageId`, `userMessage`, and `agentMessage`

```json theme={"system"}
{
  "summary": "User asked about account setup and verification steps.",
  "chatMessages": [
    {
      "messageId": "msg-003",
      "userMessage": "What documents do I need?",
      "agentMessage": "You need a valid ID and proof of address."
    },
    {
      "messageId": "msg-002",
      "userMessage": "How do I verify my account?",
      "agentMessage": "Navigate to Settings and select Verification."
    }
  ]
}
```

<Tip>
  The Memory tab only appears when `memoryUseSummary` data exists for the workflow instance. If you don't see it, verify that **Use Memory** is enabled on at least one node.
</Tip>

***

## Storage

| Data                 | Storage                          | Details                                                |
| -------------------- | -------------------------------- | ------------------------------------------------------ |
| Session ID           | Browser storage + FlowX Database | Links the client chat instance to the server session   |
| Message history      | FlowX Database                   | Complete record of user and agent messages per session |
| Conversation summary | FlowX Database                   | Auto-generated summary of older conversation turns     |
| Session metadata     | FlowX Database                   | Timestamps, workflow reference, user info              |

Session memory is tied to the `chatSessionId` — the same session ID retrieves the same memory across workflow runs. The Chat component manages session IDs automatically.

***

## Limitations

* Memory is **session-scoped** — there is no cross-session or cross-user memory
* The latest **3 turns** are always included in full; older turns are summarized
* Summarization uses an LLM call, which adds latency on the first message after the 3-turn threshold
* Memory cannot be manually edited or cleared from the Designer UI
* Only **user messages** and **agent responses** are stored — internal workflow data is excluded

***

## Related resources

<CardGroup>
  <Card title="Conversational workflows" icon="comments" href="/5.9/ai-platform/conversational-workflows">
    Full guide to building Chat Driven workflows with memory and intent routing
  </Card>

  <Card title="Chat component" icon="message" href="/5.9/ai-platform/chat-component">
    Runtime behavior, session management, and display modes
  </Card>

  <Card title="Intent Classification" icon="bullseye" href="/5.9/ai-platform/agent-builder/intent-classification">
    Route conversations based on detected user intent with optional memory
  </Card>

  <Card title="Custom Agent node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
    Configure AI nodes with memory, chat reply, and response settings
  </Card>
</CardGroup>


# AI node types
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/node-types

Understanding the different AI node types available in Agent Builder for building AI workflows.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

Agent Builder provides AI nodes organized into categories based on the type of content they process. Combine these nodes to create sophisticated workflows.

<Frame>
  ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
</Frame>

## Node categories

<CardGroup>
  <Card title="Text operations" icon="font" href="#ai-text-operations">
    Process and analyze text content
  </Card>

  <Card title="Document operations" icon="file-lines" href="#ai-document-operations">
    Work with documents and files
  </Card>

  <Card title="Image operations" icon="image" href="#ai-image-operations">
    Analyze visual content
  </Card>

  <Card title="Data operations" icon="database" href="#ai-data-operations">
    Transform and enrich data
  </Card>
</CardGroup>

Additionally, the **Custom Agent**, **Context Retrieval**, **Intent Classification**, and **Speech to Text** nodes provide specialized capabilities.

***

## Intent Classification

Classify user messages and automatically route the workflow to the matching branch — combining AI classification and conditional branching in a single node.

| Node type                 | Description                                                                      | Use cases                                                    |
| ------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Intent Classification** | Classifies a user message into defined intents and routes to the matching branch | Chatbot routing, email triage, support ticket classification |

### Configuration options

* **User message** — Input text to classify (supports `${}` references)
* **Intents** — Up to 10 natural language intent descriptions, each becoming an output branch
* **Use memory** — Include conversation history for context-aware classification
* **Include Reason for Selection** — Add LLM explanation for the chosen intent
* **Fallback branch** — Automatic "If No Intent Matches" path

<Card title="Intent Classification" icon="arrows-split-up-and-left" href="./intent-classification">
  Learn more about configuring intents, output format, and routing behavior
</Card>

***

## Context Retrieval

Perform RAG (Retrieval-Augmented Generation) searches against a Knowledge Base and return relevant chunks — without calling an LLM.

| Node type             | Description                                                                | Use cases                                                                 |
| --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Context Retrieval** | Queries a Knowledge Base and returns matching chunks with relevance scores | RAG pipelines, document search, context gathering for downstream AI nodes |

### Configuration options

* **Source** — Knowledge Base or Memory (Memory only available in conversational workflows)
* **Knowledge Base** — Select which Knowledge Base to query (when source is Knowledge Base)
* **User Query** — the search query, supports process variable expressions
* **Search type** — Hybrid (default), Semantic, or Keywords
* **Max Number of Chunks** — how many chunks to return (1-10)
* **Min Relevance Score** — minimum relevance threshold (0-100%)
* **Metadata Filters** — structured filters with typed operators and AND/OR grouping to refine results by chunk metadata
* **Use advance metadata filters** — toggle for expression-based filtering
* **Use Re-rank** — re-rank retrieved chunks before returning

### Output format

The node outputs an array of retrieved chunks, each containing:

| Field            | Description                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `chunkContent`   | The text content of the retrieved chunk                                                                                                   |
| `chunkMetadata`  | Metadata associated with the chunk                                                                                                        |
| `relevanceScore` | Similarity score between the query and the chunk                                                                                          |
| `searchType`     | Search strategy that returned this chunk: `HYBRID`, `SEMANTIC`, or `KEYWORD`. Only emitted when the RAG service returns a non-null value. |
| `contentSource`  | The store the chunk belongs to (field name preserved for API compatibility)                                                               |

<Card title="Context Retrieval" icon="magnifying-glass" href="./context-retrieval">
  Learn more about configuring Context Retrieval nodes
</Card>

***

## Custom Agent

Create custom agents with advanced capabilities powered by Model Context Protocol (MCP) tools, optional Knowledge Base retrieval, and direct chat reply in Chat Driven workflows.

| Node type               | Description                      | Use cases                         |
| ----------------------- | -------------------------------- | --------------------------------- |
| **Text generation**     | Create text content from prompts | Reports, summaries, responses     |
| **Summarization**       | Condense long content            | Document summaries, meeting notes |
| **Translation**         | Convert between languages        | Multi-language support            |
| **Document completion** | Fill in templates                | Form letters, contracts           |

### Configuration options

* **Instructions** *(mandatory)* — The agent's role, tasks, and expected input/output. Sent as the System message and **cached** by the LLM between executions, so `${variable}` references are not allowed in this field.
* **Background → Use conversation memory** — Include conversation history in the LLM call (Chat Driven workflows only)
* **Background → Knowledge Base** — Attach a knowledge base for RAG retrieval; includes Search Type (vector / keyword / hybrid) and Re-rank options
* **Background → Context** — Free-text field for the per-execution prompt; supports `${variable}` references. Sent as the User message and not cached.
* **Background → Use only referenced values as input** — Send only values referenced in the prompt to the LLM; narrows context and reduces token usage
* **Tools → MCP Servers** — Attach MCP tools the agent can call
* **Tools → Built-in tools → Use Web Search Tool** — Toggle **ON** to let the agent look up recent information from the public web. Off by default.
* **Personal Information Guard** — Toggle PII redaction on the node's input and/or output
* **Response → Send as Chat Reply** — In Chat Driven workflows, deliver the response directly to the Chat component as Markdown
* **Response → Include Task for Prompt Suggestions** — In Chat Driven workflows, generate AI follow-up prompts shown in the Chat component after the response
* **Response Key** — Key where the node output is stored in the workflow data
* **Response Schema** — Expected JSON structure of the LLM response (hidden when Send as Chat Reply is ON)

<Card title="Custom Agent in Chat Driven workflows" icon="comments" href="/5.9/ai-platform/conversational-workflows#custom-agent-node">
  Full reference for Use Memory, Send as Chat Reply, Prompt Suggestions, and other Chat Driven specifics
</Card>

***

## Speech to Text

Transcribe audio to text within integration workflows.

| Node type          | Description                                                                      | Use cases                                                                                               |
| ------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Speech to Text** | Transcribe audio files into text with language detection and confidence metadata | Voice message processing, audio transcription, accessibility, conversational workflows with voice input |

### Configuration options

* **File Source** — Document Plugin, S3, or Chat Input (conversational workflows)
* **File Path** — Path to the audio file (supports `${}` references); becomes a test-file dropdown when **Use Test File** is on
* **Use Test File** — Upload a sample audio file for development testing
* **Response Key** — Key under which the transcript and metadata are stored

<Card title="Speech to Text" icon="microphone" href="./speech-to-text">
  Learn more about configuring transcription, text-to-speech, and chat voice integration
</Card>

***

## Understanding nodes

Understanding nodes analyze content to extract meaning and intent.

| Node type                    | Description                        | Use cases                         |
| ---------------------------- | ---------------------------------- | --------------------------------- |
| **Sentiment analysis**       | Detect emotional tone              | Customer feedback, reviews        |
| **Topic modeling**           | Identify themes and subjects       | Document categorization           |
| **Intent recognition**       | Understand user goals              | Chatbot routing, request handling |
| **Named entity recognition** | Find people, places, organizations | Data extraction, compliance       |

### Configuration options

* **Classification labels** - Define categories for classification
* **Confidence threshold** - Minimum score for results
* **Multi-label** - Allow multiple classifications per input

***

## AI Document Operations

Process documents to extract data, generate reports, or understand content.

| Node                       | Description                                                                             | Use cases                                                            |
| -------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Document Generation**    | Automatically build reports or complete templates based on given inputs                 | Report generation, template completion                               |
| **Document Extraction**    | Identify and extract structured data, entities or metadata from documents               | Form processing, invoice data extraction                             |
| **Document Understanding** | Analyze documents to extract meaning, topics, sentiment, or important information       | Document classification, content analysis                            |
| **Extract Data from File** | Extract text and data from documents and images with configurable extraction strategies | OCR, PDF text extraction, image data extraction, signature detection |

<Card title="Extract Data from File" icon="file-lines" href="./extract-data-from-file">
  Learn more about configuring extraction strategies, image extraction, and signature detection
</Card>

### Configuration options

* **Document type** - Specify expected document format
* **Schema definition** - Define expected output structure
* **Field mapping** - Map extracted fields to data model
* **Confidence threshold** - Minimum score for extractions

***

## AI Image Operations

Analyze visual content to generate captions, extract details, or identify objects.

| Node type                 | Description               | Use cases                                  |
| ------------------------- | ------------------------- | ------------------------------------------ |
| **Object recognition**    | Identify items in images  | Document classification, damage assessment |
| **Text extraction (OCR)** | Read text from images     | Invoice processing, ID verification        |
| **Scene understanding**   | Interpret image context   | Property assessment, claims processing     |
| **Emotion analysis**      | Detect facial expressions | Customer experience, fraud detection       |

### Configuration options

* **Detection confidence** - Minimum threshold for detections
* **Region of interest** - Focus on specific image areas
* **Output format** - Structured data or annotations

***

## Combining nodes

Nodes can be connected in workflows to create complex processing pipelines:

```
Document Input → Text Extraction → Entity Recognition → Validation → Output
```

### Best practices

<AccordionGroup>
  <Accordion title="Start simple" icon="1">
    Begin with a single node and add complexity incrementally. Test each addition before moving on.
  </Accordion>

  <Accordion title="Use validation nodes" icon="check">
    Add validation steps after extraction to ensure data quality before processing continues.
  </Accordion>

  <Accordion title="Handle errors" icon="triangle-exclamation">
    Include fallback paths for when nodes fail or return low-confidence results.
  </Accordion>

  <Accordion title="Monitor performance" icon="chart-line">
    Track execution times and accuracy metrics to identify bottlenecks and improvement opportunities.
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup>
  <Card title="Agent Builder overview" icon="robot" href="./overview">
    Get started with Agent Builder
  </Card>

  <Card title="Use cases" icon="lightbulb" href="./use-cases">
    See real-world examples
  </Card>

  <Card title="Conversational workflows" icon="messages" href="../conversational-workflows">
    Multi-turn chat with Custom Agent node changes for chat replies and memory
  </Card>
</CardGroup>


# Agent Builder
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/overview

Create custom AI agents without code using the FlowX Agent Builder - a no-code/low-code platform for business users.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

The FlowX Agent Builder is a no-code/low-code platform that enables business users to create custom AI agents without relying on IT or data science teams.

```mermaid theme={"system"}
flowchart LR
    subgraph sources [" "]
        KB[Knowledge Base]
        API[APIs]
        DB[Database]
    end

    sources --> BUILD

    subgraph BUILD [Agent Builder]
        C[Configure] --> T[Test] --> D[Deploy]
    end

    D --> Chat
    D --> Workflows
    D --> API2[REST API]
```

Agents connect to your data through multiple integration options:

* **Knowledge Bases** - Ground responses in your documents using RAG
* **MCP servers** - Connect external tools via Model Context Protocol
* **REST APIs** - Call any HTTP endpoint
* **FlowX Database** - Query and store structured data
* **Kafka** - Event-driven integrations

## What can you build?

Agent Builder allows you to create specialized AI agents that can:

<CardGroup>
  <Card title="Process documents" icon="file-lines">
    Extract, validate, and analyze data from various document types
  </Card>

  <Card title="Understand content" icon="brain">
    Perform sentiment analysis, topic modeling, and named entity recognition
  </Card>

  <Card title="Generate content" icon="wand-magic-sparkles">
    Create summaries, translations, and complete documents
  </Card>

  <Card title="Analyze images" icon="image">
    Recognize objects, extract text, and understand scenes
  </Card>

  <Card title="Make decisions" icon="scale-balanced">
    Provide risk assessments and compliance checks with full auditability
  </Card>
</CardGroup>

## Key benefits

### Business empowerment

* **Drag-and-drop interface** accessible to non-technical users
* **Pre-built templates** for common use cases
* **Reduced time-to-market** for AI solutions

### Enterprise-grade features

* **Full audit trails** and explainable AI decisions
* **Integration with existing workflows** and systems
* **Compliance-ready** with regulatory requirements
* **Tool call limit** — agents are capped at 20 tool calls per run to prevent runaway operations

## Core agent categories

<AccordionGroup>
  <Accordion title="Document processing agents" icon="file-invoice">
    * Document extraction and validation
    * Cross-document consistency checks
    * Metadata creation and classification
  </Accordion>

  <Accordion title="Analysis agents" icon="chart-line">
    * Sentiment and emotion analysis
    * Risk assessment and fraud detection
    * Customer behavior analysis for upselling
  </Accordion>

  <Accordion title="Generation agents" icon="pen-nib">
    * Report writing and document completion
    * Content summarization and paraphrasing
    * Multi-language translation
  </Accordion>
</AccordionGroup>

## Getting started

<Steps>
  <Step title="Choose your approach">
    * Start with **pre-built templates** for common scenarios
    * Create **from scratch** with custom instructions
  </Step>

  <Step title="Configure your agent">
    * Define input sources (documents, images, structured data)
    * Set processing logic and validation rules
    * Configure output formats and destinations
  </Step>

  <Step title="Test and deploy">
    * Test with sample documents and data
    * Review confidence scores and validation results
    * Deploy into your FlowX workflows
  </Step>
</Steps>

## Agent Designer interface

The Agent Designer provides a visual canvas for building AI workflows:

| Component      | Description                                          |
| -------------- | ---------------------------------------------------- |
| **Left panel** | Available actions and node types to drag onto canvas |
| **Canvas**     | Visual workflow designer where you connect nodes     |
| **Properties** | Configuration panel for selected nodes               |
| **Test panel** | Run tests with sample data                           |

## Related resources

<CardGroup>
  <Card title="Node types" icon="diagram-project" href="./node-types">
    Learn about Generation, Understanding, Extraction, and Analysis nodes
  </Card>

  <Card title="Use cases" icon="lightbulb" href="./use-cases">
    Real-world examples: loan processing, mortgage validation, customer intelligence
  </Card>

  <Card title="Config-time agents" icon="pencil-ruler" href="../pre-built-agents/overview">
    Design-time AI assistants for FlowX Designer
  </Card>

  <Card title="Using agents" icon="play" href="../using-agents/overview">
    Learn how to integrate agents into your apps
  </Card>

  <Card title="Conversational workflows" icon="messages" href="../conversational-workflows">
    Build multi-turn chat experiences with session memory and intent routing
  </Card>
</CardGroup>


# Speech to Text
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/speech-to-text

Transcribe audio to text within integration workflows.

## Overview

The **Speech to Text** node is a workflow node that transcribes audio files into text. It reads audio from a configured source, sends it to the speech-to-text service, and returns the transcript along with language detection and confidence metadata. The node works in both standard and conversational workflows, and integrates with the FlowX Document Plugin for file storage.

<Frame>
  ![Speech to Text node configuration in Integration Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/speech_to_text.png)
</Frame>

<CardGroup>
  <Card title="Transcribe audio" icon="file-audio">
    Convert audio recordings to text with language detection and confidence scores
  </Card>

  <Card title="Multiple file sources" icon="folder-open">
    Read audio from Document Plugin, S3, or directly from chat voice input
  </Card>

  <Card title="Chat integration" icon="comments">
    Automatically processes voice messages in conversational workflows
  </Card>

  <Card title="Test files for development" icon="flask">
    Upload sample audio to validate your workflow before connecting a live source
  </Card>
</CardGroup>

***

## Configuration

<Steps>
  <Step title="Open your workflow">
    Open your workflow in **Integration Designer**.
  </Step>

  <Step title="Add the node">
    Add a **Speech to Text** node from the node palette.
  </Step>

  <Step title="Configure the settings">
    Configure the settings described below.
  </Step>
</Steps>

***

### File Source

<ParamField type="enum">
  Where the audio file is located.

  | Source              | Description                                                     | Availability                  |
  | ------------------- | --------------------------------------------------------------- | ----------------------------- |
  | **Document Plugin** | Read audio from a file stored in the FlowX Document Plugin      | Standard workflows            |
  | **S3 Protocol**     | Read audio from S3-compatible storage                           | Standard workflows            |
  | **Chat Input**      | Automatically receive audio from a voice message in the chat UI | Conversational workflows only |

  In conversational workflows, the file source is set to **Chat Input** automatically.

  <Frame>
    ![Voice input configuration on a conversational workflow Start node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/voice_input_start_wkf_node.png)
  </Frame>
</ParamField>

<ParamField type="boolean">
  Upload and use a sample audio file for testing without connecting a live source. When turned on, **File Path** becomes a dropdown of available test files instead of a free-text input.

  **Default:** OFF
</ParamField>

<ParamField type="string">
  Path to the audio file. The control changes based on **Use Test File**:

  * **Use Test File OFF** — free-text input. Supports `${expression}` placeholders for dynamic values from workflow data. Only meaningful when **File Source** is `Document Plugin` or `S3 Protocol`.
  * **Use Test File ON** — dropdown labelled **Select Test File**, listing the test files uploaded to this node.

  **Example:** `${inputData.audioFilePath}`
</ParamField>

<ParamField type="string">
  The key under which the transcript and metadata are stored in the workflow data.

  **Example:** `speechResult`
</ParamField>

***

## Supported audio formats

| Format | MIME Type     |
| ------ | ------------- |
| MP3    | `audio/mpeg`  |
| WAV    | `audio/wav`   |
| M4A    | `audio/x-m4a` |
| AAC    | `audio/aac`   |
| OGG    | `audio/ogg`   |

## File size limits

| Workflow type  | Maximum size |
| -------------- | ------------ |
| Conversational | 5 MB         |
| Standard       | 10 MB        |

Test files support the same audio formats listed above, with a maximum size of 15 MB.

***

## Output

The node writes the transcript and metadata under the configured **Response Key**.

**Standard workflows** output nested under the response key:

```json theme={"system"}
{
  "responseKey": {
    "transcript": "The transcribed text content",
    "language": "en",
    "confidence": 1.0,
    "responseTime": 2.34,
    "audioFileName": "recording.mp3"
  }
}
```

**Conversational workflows** output at the top level for chat integration:

```json theme={"system"}
{
  "userMessage": "The transcribed text content",
  "userMessageConfidence": 1.0
}
```

| Field                                  | Type   | Description                                     |
| -------------------------------------- | ------ | ----------------------------------------------- |
| `transcript` / `userMessage`           | string | The transcribed text                            |
| `language`                             | string | Detected language code (e.g., `en`, `fr`, `de`) |
| `confidence` / `userMessageConfidence` | number | Confidence score (0.0 to 1.0)                   |
| `responseTime`                         | number | Processing time in seconds                      |
| `audioFileName`                        | string | Original audio file name                        |

***

## Conversational workflow integration

In conversational workflows, the Speech to Text node works with the [Chat component](/5.9/ai-platform/chat-component) voice input feature:

1. A user records a voice message in the chat UI
2. The audio file is sent to the workflow as a chat input
3. The Speech to Text node (with **Chat Input** file source) transcribes the audio
4. The transcript is set as the `userMessage`, making it available to downstream nodes (Custom Agent, Intent Classification) as if the user had typed it

<Info>
  When processing chat voice input, the audio file metadata is preserved in the conversation context. This allows conversation history to reference which messages originated from voice input.
</Info>

***

## Node connections

The Speech to Text node has two output handles:

| Handle      | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| **Success** | The transcription completed and output is available under the response key   |
| **Fail**    | The transcription failed (unsupported format, file not found, service error) |

Connect downstream nodes to the appropriate handle to manage both successful and failed transcription scenarios.

***

## Best practices

<CardGroup>
  <Card title="Match file source to workflow type" icon="arrows-split-up-and-left">
    Use **Chat Input** for conversational workflows and **Document Plugin** or **S3** for standard workflows.
  </Card>

  <Card title="Keep audio files within size limits" icon="weight-scale">
    Audio files exceeding the size limit (5 MB conversational, 10 MB standard) will fail. Validate file size before reaching the node if the source is user-provided.
  </Card>

  <Card title="Use test files during development" icon="flask">
    Upload a sample audio file to validate your workflow configuration before connecting to a live source.
  </Card>

  <Card title="Handle failures" icon="triangle-exclamation">
    Always connect the **Fail** handle to a fallback path, especially when processing user-uploaded audio that may be in an unsupported format.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Chat component" icon="comments" href="/5.9/ai-platform/chat-component">
    Voice input and conversational UI for chat-based workflows
  </Card>

  <Card title="Conversational workflows" icon="messages" href="/5.9/ai-platform/conversational-workflows">
    Build multi-turn conversations with AI Triggers and context
  </Card>

  <Card title="AI node types" icon="diagram-project" href="./node-types">
    Overview of all AI workflow node types
  </Card>

  <Card title="Integration Designer" icon="sitemap" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Build and manage integration workflows
  </Card>
</CardGroup>


# Agent Builder use cases
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/use-cases

Real-world examples of what you can build with FlowX.AI Agent Builder.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

Agent Builder supports a wide range of AI-powered automation scenarios. Below are the primary categories with examples drawn from production implementations.

## Document processing and extraction

Extract structured data from unstructured documents — invoices, contracts, shipping documents, financial statements — using TEXT\_EXTRACTION nodes with tailored prompts per document type.

<AccordionGroup>
  <Accordion title="Logistics document processing" icon="truck">
    An email-triggered pipeline processes carrier emails and their attachments:

    * **Classify** documents by type (BOL, invoice, rate confirmation, lumper receipt, fuel receipt, and more)
    * **Extract** structured fields from each document type using specialized TEXT\_EXTRACTION nodes
    * **Reconcile** extracted data against a Transportation Management System (TMS)
    * **Surface exceptions** for human review via task management

    **AI nodes used:** TEXT\_EXTRACTION (12 document types), TEXT\_UNDERSTANDING (12 comparison workflows), TEXT\_GENERATION (email summary)

    **Patterns involved:** [Fan-out extraction](../patterns/fan-out-extraction), [AI comparison](../patterns/ai-comparison-reconciliation)
  </Accordion>

  <Accordion title="Mortgage document validation" icon="building-columns">
    Process mortgage application packages by extracting product data from bank documentation:

    * **Extract** structured product details (interest rates, fees, insurance requirements) from bank product sheets
    * **Weight** income and debt values per bank-specific rules using AI extraction
    * **Validate** legal/regulatory eligibility using AI understanding

    **AI nodes used:** TEXT\_EXTRACTION (income/debt/product extraction), TEXT\_UNDERSTANDING (eligibility checks)

    **Patterns involved:** [Hybrid AI + business rules](../patterns/hybrid-ai-rules), [Fan-out extraction](../patterns/fan-out-extraction)
  </Accordion>
</AccordionGroup>

***

## Conversational AI

Build chat-based assistants that understand user intent, maintain conversation context, and provide personalized responses grounded in your data.

<AccordionGroup>
  <Accordion title="Mortgage advisor chatbot" icon="comments">
    A conversational assistant that guides users through mortgage product selection:

    * **Detect intent** — classify user messages as greetings, product inquiries, data input, or other
    * **Route** to specialized handlers (small talk, personalized offers, knowledge base Q\&A)
    * **Generate** personalized mortgage consultant reports with comparative cost tables
    * **Maintain** conversation history across sessions

    **AI nodes used:** TEXT\_UNDERSTANDING (intent detection), TEXT\_GENERATION (responses, reports), CUSTOM\_AGENT (knowledge base RAG)

    **Patterns involved:** [Intent classification](../patterns/intent-classification-routing), [Knowledge base RAG](../patterns/knowledge-base-rag), [Session state](../patterns/session-state-management)
  </Accordion>
</AccordionGroup>

***

## AI-augmented decision making

Combine AI capabilities with deterministic business logic for auditable, explainable decision-making.

<AccordionGroup>
  <Accordion title="Product eligibility and scoring" icon="scale-balanced">
    Evaluate financial product eligibility using a pipeline that mixes AI and business rules:

    * **AI extracts** income weights and debt factors from bank-specific rule documents
    * **Business rules** compute PMT, DTI ratios, maximum loan amounts, and currency conversions
    * **AI filters** products by qualitative criteria (loan type, sustainability features) with fuzzy matching
    * **Business rules** normalize scores and rank the top products
    * **AI generates** a professional consultant report with the final recommendations

    **AI nodes used:** TEXT\_EXTRACTION, TEXT\_UNDERSTANDING, TEXT\_TRANSFORMATION, TEXT\_GENERATION

    **Patterns involved:** [Hybrid AI + business rules](../patterns/hybrid-ai-rules)
  </Accordion>

  <Accordion title="Document reconciliation" icon="code-compare">
    Compare AI-extracted document data against system-of-record values:

    * **Compare** field-by-field with structured exception reporting
    * **Generate** match rates and confidence scores per document
    * **Flag** mismatches, missing fields, and derived value discrepancies
    * **Route** exceptions to human reviewers based on severity

    **AI nodes used:** TEXT\_UNDERSTANDING (comparison agents per document type)

    **Patterns involved:** [AI comparison and reconciliation](../patterns/ai-comparison-reconciliation)
  </Accordion>
</AccordionGroup>

***

## Email automation

Process incoming emails and their attachments automatically using email triggers and AI workflows.

<AccordionGroup>
  <Accordion title="Carrier email processing" icon="envelope">
    Monitor an email inbox for incoming carrier communications:

    * **Trigger** workflows automatically when emails arrive (IMAP integration)
    * **Summarize** email content and classify intent (invoice submission, payment inquiry, dispute)
    * **Extract** and process all attachments through the document pipeline
    * **Look up** related orders in external systems (TMS) by BOL number
    * **Notify** relevant staff of exceptions via email templates

    **AI nodes used:** TEXT\_GENERATION (email summary), TEXT\_EXTRACTION (attachments), TEXT\_UNDERSTANDING (comparison)

    **Data sources:** Email Trigger, REST API (TMS), FlowX Database
  </Accordion>
</AccordionGroup>

***

## Building your own use case

<Steps>
  <Step title="Identify the AI tasks">
    Map which steps in your process need AI (extraction, classification, generation, comparison) versus deterministic logic (calculations, routing, validation).
  </Step>

  <Step title="Choose your patterns">
    Select from the [AI patterns](../patterns/overview) that match your needs. Most apps combine 2-4 patterns.
  </Step>

  <Step title="Design the data flow">
    Define your data sources, data model, and how data moves between processes, workflows, and AI nodes.
  </Step>

  <Step title="Build incrementally">
    Start with a single AI node (e.g., one document type extraction), validate it works, then expand to the full pipeline.
  </Step>

  <Step title="Add human review">
    Use task management views for exception handling and quality assurance, especially for high-stakes decisions.
  </Step>
</Steps>

## Related resources

<CardGroup>
  <Card title="Tutorials" icon="graduation-cap" href="../tutorials/overview">
    End-to-end build guides based on production apps
  </Card>

  <Card title="AI patterns" icon="puzzle-piece" href="../patterns/overview">
    Reusable architectural patterns
  </Card>

  <Card title="Node types" icon="diagram-project" href="./node-types">
    Detailed node reference
  </Card>

  <Card title="Using agents" icon="play" href="../using-agents/overview">
    Deploy agents in your apps
  </Card>
</CardGroup>


# Web Page Extractor
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/web-page-extractor

Collect readable content from web page URLs with configurable crawling depth, link following, and scrape speed.

## Overview

The **Web Page Extractor** node is a workflow node that collects readable content from web page URLs. It supports static URL lists and dynamic URL generation, configurable crawling depth with link following, and adjustable scrape speed presets.

<Frame>
  ![Web Page Extractor node configuration with URLs, Crawl Depth, and Scrape Speed settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
</Frame>

<CardGroup>
  <Card title="Static or dynamic URLs" icon="link">
    Provide a fixed list of URLs or generate them dynamically from workflow data
  </Card>

  <Card title="Link following" icon="diagram-project">
    Optionally follow links on pages up to a configurable depth
  </Card>

  <Card title="PDF processing" icon="file-pdf">
    Extract content from PDF files linked on the page
  </Card>

  <Card title="Scrape speed control" icon="gauge-high">
    Choose from speed presets or define custom rate limits and concurrency
  </Card>

  <Card title="File downloads" icon="download">
    Download attached files (.docx, .xlsx, .pdf) found during crawling and store them automatically
  </Card>
</CardGroup>

***

## Configuration

<Steps>
  <Step title="Open your workflow">
    Open your workflow in **Integration Designer**.
  </Step>

  <Step title="Add the node">
    Add a **Web Page Extractor** node from the **Tools** category in the left panel.
  </Step>

  <Step title="Configure URL source and extraction settings">
    Configure the settings described below.
  </Step>
</Steps>

***

### URL source

<ParamField type="enum">
  How URLs are provided to the node.

  | Mode        | Description                                                         |
  | ----------- | ------------------------------------------------------------------- |
  | **Static**  | Provide a fixed list of up to 20 URLs                               |
  | **Dynamic** | Generate URLs from a workflow data key using `${expression}` syntax |

  **Default:** `Static`
</ParamField>

<ParamField type="string[]">
  List of URLs to extract content from. Only available when **URL Mode** is `Static`.

  **Maximum:** 20 URLs

  URLs must use `http://` or `https://` protocol. Supports `${variable}` placeholders for dynamic values.
</ParamField>

<ParamField type="string">
  A workflow data key or expression that resolves to a URL at runtime. Only available when **URL Mode** is `Dynamic`.

  **Example:** `${inputData.targetUrl}`
</ParamField>

***

### Crawl depth

<ParamField type="boolean">
  When turned on, the extractor follows links found on the page up to the configured depth.

  **Default:** OFF
</ParamField>

<ParamField type="number">
  How many levels of links to follow from the starting page. Only available when **Follow Links** is turned on. Displayed in the panel as a slider with the current value shown to the right (for example, *2 levels*).

  **Range:** 0–10

  **Default:** `0`
</ParamField>

<ParamField type="string[]">
  Optional list of substring filters applied to discovered links — only URLs that contain at least one of the configured fragments are followed. Click **Set Filters** to open the filter editor. Only available when **Follow Links** is turned on.
</ParamField>

<ParamField type="boolean">
  When turned on, extracts content from PDF files linked on the page. Only available when **Follow Links** is turned on.

  **Default:** OFF
</ParamField>

***

### Download attached files

When turned on, the extractor downloads attached files (.docx, .xlsx, .pdf) found during crawling and stores them using the configured document destination.

<ParamField type="boolean">
  When turned on, files discovered during crawling are downloaded and stored automatically. Supported file types include `.docx`, `.xlsx`, and `.pdf`.

  **Default:** OFF
</ParamField>

<ParamField type="enum">
  Where downloaded files are stored. Only available when **Download Attached Files** is turned on.

  | Option              | Description                                                              |
  | ------------------- | ------------------------------------------------------------------------ |
  | **Document Plugin** | Store files through the FlowX Document Plugin. Requires **Folder Name**. |
  | **S3 Protocol**     | Store files directly using S3-compatible storage.                        |
</ParamField>

<ParamField type="string">
  Identifier used to associate the file with its business owner. Only available when **Download Attached Files** is turned on and **Document Destination** is `Document Plugin`.
</ParamField>

***

### Scrape speed

<ParamField type="enum">
  Controls how aggressively the node requests pages from the target server.

  | Preset       | Description                                                             |
  | ------------ | ----------------------------------------------------------------------- |
  | **Slow**     | Conservative rate limiting — best for fragile or rate-limited servers   |
  | **Moderate** | Balanced speed and reliability                                          |
  | **Fast**     | Aggressive crawling — assumes the target server can handle high traffic |
  | **Custom**   | Define your own rate limit and concurrency                              |

  **Default:** `Moderate`
</ParamField>

<ParamField type="number">
  Maximum requests per second. Displayed in the panel as a slider labelled in `req/s`. Only available when **Scrape Speed** is `Custom`.

  **Default:** `2 req/s`
</ParamField>

<ParamField type="number">
  Number of concurrent requests. Displayed in the panel as a slider labelled in `parallel`. Only available when **Scrape Speed** is `Custom`.

  **Default:** `3 parallel`
</ParamField>

***

### Response key

<ParamField type="string">
  The key where extracted content is stored in the workflow data.

  **Example:** `extractedContent`
</ParamField>

***

### Timeout and retry

<ParamField type="number">
  Request timeout in milliseconds. If the extraction exceeds this duration, the node fails.
</ParamField>

<ParamField type="object">
  Optional retry strategy for failed requests.

  | Field                  | Description                                | Default  |
  | ---------------------- | ------------------------------------------ | -------- |
  | **Retry Type**         | `Fixed` or `Exponential` backoff           | —        |
  | **Max Attempts**       | Maximum retry attempts                     | `2`      |
  | **Backoff Period**     | Delay between retries (ms)                 | `1000`   |
  | **Max Backoff Period** | Maximum delay for exponential backoff (ms) | `120000` |
  | **Backoff Multiplier** | Multiplier for exponential backoff         | `2`      |
</ParamField>

***

## Best practices

<CardGroup>
  <Card title="Start with Moderate speed" icon="gauge">
    Use the Moderate preset unless you know the target server's capacity. Switch to Fast only for internal or robust servers.
  </Card>

  <Card title="Limit crawl depth" icon="layer-group">
    Keep **Depth of Crawling** low (1–3) to avoid excessive page requests. Deep crawls can be slow and may trigger rate limiting.
  </Card>

  <Card title="Use dynamic URLs for runtime flexibility" icon="code">
    When the target URL comes from user input or a previous workflow step, use Dynamic mode with `${expression}` placeholders.
  </Card>

  <Card title="Set timeouts for external sites" icon="clock">
    Always configure a timeout when crawling external websites to avoid blocking the workflow on slow or unresponsive servers.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Extract Data from File" icon="file-lines" href="./extract-data-from-file">
    Extract text and data from documents and images
  </Card>

  <Card title="AI node types" icon="diagram-project" href="./node-types">
    Overview of all AI workflow node types
  </Card>

  <Card title="Integration Designer" icon="sitemap" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Build and manage integration workflows
  </Card>
</CardGroup>


# AI in FlowX
Source: https://docs.flowx.ai/5.9/ai-platform/ai-in-flowx

AI agents for every stage - config-time agents help you build apps faster, while business agents power intelligent experiences for your end-users.

FlowX AI Platform provides intelligent agents across your entire application lifecycle. Whether you're building apps or running them, AI agents accelerate your work and enhance user experiences.

<img alt="FlowX AI Platform" />

<img alt="FlowX AI Platform" />

***

## Two types of AI agents

FlowX provides agents for different stages of your application lifecycle:

```mermaid theme={"system"}
flowchart LR
    subgraph config [Config Time]
        Designer[FlowX Designer + Config Agents]
    end

    subgraph build [Build]
        AB[Agent Builder]
        MP[Marketplace]
    end

    subgraph runtime [Runtime]
        BA[Business Agents] --> Users[End Users]
    end

    Designer -.->|help build| AB
    AB --> BA
    MP --> BA
```

<CardGroup>
  <Card title="Config-time agents" icon="pencil-ruler">
    **Help you build apps faster**

    AI assistants embedded in FlowX Designer that help developers and business analysts create processes, UIs, and business rules.

    Used by: Designers, developers, analysts
  </Card>

  <Card title="Business agents" icon="briefcase">
    **Power your end-user experiences**

    AI agents that run inside your applications, interacting with customers and employees to automate tasks and provide intelligent assistance.

    Used by: Your customers and employees
  </Card>
</CardGroup>

***

## Config-time agents

These agents are built into FlowX Designer to accelerate app development:

<CardGroup>
  <Card title="Analyst" icon="magnifying-glass-chart" href="./pre-built-agents/ai-analyst">
    Build and optimize BPMN processes using AI to generate, validate, and enhance workflows
  </Card>

  <Card title="Assistant" icon="message-bot" href="./pre-built-agents/ai-assistant">
    Answer questions about FlowX platform and your organization based on documentation
  </Card>

  <Card title="Designer" icon="palette" href="./pre-built-agents/ai-designer">
    Convert natural language prompts, Figma designs, or sketches into UI layouts
  </Card>

  <Card title="Developer" icon="code" href="./pre-built-agents/ai-developer">
    Generate business rules and code expressions using natural language
  </Card>
</CardGroup>

<Accordion title="See config-time agents in action">
  <video />
</Accordion>

<Card title="Learn more about config-time agents" icon="sparkles" href="./pre-built-agents/overview">
  Detailed documentation for each config-time agent
</Card>

***

## Business agents

Agents that power intelligent experiences for your end-users. You have two options:

### FlowX accelerators

Pre-built business agents created by FlowX, ready to deploy:

* Industry-specific solutions for banking, insurance, and more
* Tested and optimized for common use cases
* Deploy immediately or customize to your needs

### Custom agents

Use **Agent Builder** to create AI agents tailored to your specific business processes:

* **Document processing** - Extract data from forms, contracts, and statements
* **Content generation** - Create personalized communications and reports
* **Decision support** - Analyze data and provide recommendations
* **Conversational AI** - Build chat-based customer interactions

<Card title="Agent Builder" icon="hammer" href="./agent-builder/overview">
  Create custom AI agents for your specific business needs
</Card>

***

## Integrating agents into apps

Once you have business agents (custom or from marketplace), integrate them into your applications:

<CardGroup>
  <Card title="Chat interface" icon="comments" href="./using-agents/chat-interface">
    Conversational UI for end-users
  </Card>

  <Card title="BPMN integration" icon="diagram-project" href="./using-agents/bpmn-integration">
    Trigger agents from workflows
  </Card>

  <Card title="API access" icon="code" href="./integrations">
    Programmatic integration
  </Card>
</CardGroup>

***

## Enterprise security

<img alt="Enterprise Security" />

<img alt="Enterprise Security" />

All FlowX AI agents are built for banking-grade security:

| Security feature             | Description                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| **Zero-trust model**         | All components authenticate each other, preventing unauthorized access |
| **Input/output scanning**    | Detect prompt injection, ban sensitive substrings, sanitize outputs    |
| **Custom fine-tuned models** | Purpose-built models with curated data for each use case               |
| **Human oversight**          | Human-in-the-loop controls for ethical decision-making                 |

***

## Personal data protection

FlowX ensures personal data never reaches AI models by design through controlled data ingestion, deterministic workflows, and encryption options.

### Data ingestion paths

Personal data enters the platform through three channels:

| Channel            | Data handling                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Forms / UIs**    | Input data mapped directly to the process data model                                                                                      |
| **3rd party APIs** | API responses mapped to the process data model                                                                                            |
| **Documents**      | Structured docs (Word, Excel) have fields mapped automatically; unstructured docs require OCR extraction with optional human verification |

<Info>
  For unstructured documents containing sensitive data, a human operator can verify extracted data accuracy before it's mapped to the data model.
</Info>

### Data storage

All ingested data ends up in **data models** - JSON collections stored in FlowX databases:

* Data models are only accessible to deterministic business process steps
* Process logic controls when, how, and which data is sent to AI steps
* This ensures **no personal data is sent to AI by design**

### Protection options

| Option                     | Description                                                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Database encryption**    | Encrypt data at rest using database capabilities (e.g., pgcrypto in PostgreSQL) - prevents administrator access to business data |
| **Sensitive data masking** | Mark specific data model fields as sensitive to hide them in UIs and console outputs                                             |
| **Custom guardrails**      | Additional guardrails can be enforced in AI workflows                                                                            |

<CardGroup>
  <Card title="Data Model" icon="database" href="../docs/building-blocks/process/data-model">
    Learn about process data models
  </Card>

  <Card title="Sensitive Data" icon="eye-slash" href="../docs/building-blocks/process/data-model#sensitive-data">
    Configure sensitive data masking
  </Card>
</CardGroup>

***

## Hallucination prevention

<img alt="Hallucination Prevention" />

<img alt="Hallucination Prevention" />

| Technique                    | Purpose                                                         |
| ---------------------------- | --------------------------------------------------------------- |
| **RAG**                      | Ground responses in reliable external data sources              |
| **Multi-agent architecture** | Dedicated agents for specific tasks with specialized processing |
| **Structured outputs**       | Enforce JSON outputs for consistent, parseable responses        |
| **Model evaluation**         | Continuous testing to find optimal models for each task         |
| **Prompt tuning**            | Task-specific prompts to enhance accuracy and relevance         |

***

## Related resources

<CardGroup>
  <Card title="Chat component" icon="comments" href="./chat-component">
    Technical reference for chat integration
  </Card>

  <Card title="AI integrations" icon="plug" href="./integrations">
    Connect agents to knowledge bases and external systems
  </Card>

  <Card title="AI Platform setup" icon="gear" href="./ai-platform-setup">
    Configure AI Platform for your environment
  </Card>

  <Card title="Using agents" icon="play" href="./using-agents/overview">
    Integration patterns and best practices
  </Card>
</CardGroup>


# AI Platform setup
Source: https://docs.flowx.ai/5.9/ai-platform/ai-platform-setup

Infrastructure requirements, service configuration, and deployment guide for the FlowX.AI AI Platform.

<Warning>
  **AI Platform is required infrastructure in 5.5+.** The `integration-designer` core service has hard startup dependencies on AI Platform endpoints (`flowx.ai-service.base-url`, `flowx.kb-rag.host`, `flowx.kb-rag.port`). These have no defaults and no `@ConditionalOnProperty` flag — the service will fail to start if they are missing.

  To run FlowX without AI features, you still need to deploy the AI Platform chart (or point the env vars at reachable stub endpoints). Hiding AI surfaces (the AI floating action button, Chat UI component, AI agents) is controlled separately and has two paths:

  * **Globally — deployment-level kill switch.** Set `flowx.feature-availability.aiServiceName` on the `admin` service to a service name that is not deployed in your environment. The `/api/init` response then reports `environmentConfiguration.admin-mngt.ai-is-enabled: false`, and the Designer hides AI surfaces for everyone regardless of role. This is the right option for deployments that do not use AI at all.
  * **Per-user — role permissions.** Strip the AI permission keys (`aiagent_edit`, `org_ai_providers_*`, `wks_ai_models_*`) from specific roles via the role-mapper. See the [Complete roles & permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix).

  Both gates apply: AI surfaces appear only when `ai-is-enabled` is true **and** the user has `aiagent_edit` on the project.
</Warning>

## Overview

The AI Platform consists of two layers:

* **Python services** — AI agent and orchestration services for planning, code generation, analysis, design, knowledge retrieval, and embeddings (REST + gRPC)
* **Event-driven workers** — Background services consuming Kafka topics for knowledge-base indexing

All inter-service communication uses gRPC with Protobuf contracts, except the config-time agents (AI Developer, AI Analyst, AI Designer) and Agent Builder, which expose REST endpoints.

***

## Infrastructure requirements

<CardGroup>
  <Card title="Qdrant" icon="vector-square">
    Vector database for embeddings. Cluster mode recommended for production.
  </Card>

  <Card title="S3-compatible storage" icon="hard-drive">
    Object storage for binaries and files. Any S3-compatible provider works (MinIO, AWS S3, etc.).
  </Card>

  <Card title="Kafka" icon="bolt">
    Message broker for event-driven communication. KRaft mode supported.
  </Card>

  <Card title="Keycloak" icon="shield-halved">
    Identity provider for OAuth2 authentication across all services.
  </Card>

  <Card title="SpiceDB" icon="lock">
    Fine-grained authorization system for access control.
  </Card>
</CardGroup>

***

## Service architecture

The AI Platform is a set of Python services. In Kubernetes, every service listens on port **9100** (set via the `SERVICE_PORT` variable).

| Service (Kubernetes name)              | Protocol     | Purpose                                                                                    |
| -------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `ai-platform-planner`                  | gRPC         | Generates execution plans from user prompts (intent understanding and orchestration)       |
| `ai-platform-agent-builder`            | gRPC         | Configuration and runtime for low-code AI nodes                                            |
| `ai-platform-knowledgebase-rag`        | gRPC         | Retrieval-augmented generation over the knowledge base                                     |
| `ai-platform-embedder`                 | gRPC         | Embedding generation (also consumes durable embedding jobs from Kafka)                     |
| `ai-platform-knowledgebase-indexer-v2` | Kafka worker | Generates retrieval vectors; event-driven, consumes the knowledge-base index-request topic |
| `ai-platform-ai-analyst`               | HTTP         | Process-design expertise (config-time agent)                                               |
| `ai-platform-ai-assistant`             | HTTP         | FlowX.AI documentation assistant                                                           |
| `ai-platform-ai-designer`              | HTTP         | UI design and implementation expertise (config-time agent)                                 |
| `ai-platform-ai-developer`             | HTTP         | Coding expertise (config-time agent)                                                       |

<Info>
  The Designer AI chat surface routes through the **`ai-gateway`** service (part of the core services), which calls `ai-platform-planner` and the agent services. The **`evals-judge`** worker, deployed alongside the AI Platform, consumes `ai.flowx.ai-platform.evals-judge.job.request.v1` for [evaluations](./evaluations).
</Info>

***

## Environment variables

<Tabs>
  <Tab title="Service discovery">
    These variables control how services locate each other within the cluster:

    | Environment Variable            | Description                                  | Default Value       |
    | ------------------------------- | -------------------------------------------- | ------------------- |
    | `GRPC_HOST_RESOLVER`            | Service discovery method                     | `k8s`               |
    | `GRPC_HOST_RESOLVER_HELM_CHART` | Helm chart name for K8s service resolution   | —                   |
    | `GRPC_HOST_RESOLVER_FIXED_IP`   | Fixed IP/hostname when using `host` resolver | `ai-platform`       |
    | `SERVICE_PORT`                  | Port the service listens on                  | `9100` (production) |

    **Kubernetes deployment:**

    ```bash theme={"system"}
    GRPC_HOST_RESOLVER=k8s
    GRPC_HOST_RESOLVER_HELM_CHART=ai-platform
    ```

    **Docker Compose / local deployment:**

    ```bash theme={"system"}
    GRPC_HOST_RESOLVER=host
    GRPC_HOST_RESOLVER_FIXED_IP=localhost
    ```
  </Tab>

  <Tab title="Authentication">
    | Environment Variable              | Description                   | Default Value |
    | --------------------------------- | ----------------------------- | ------------- |
    | `SECURITY_OAUTH2_BASE_SERVER_URL` | Keycloak auth server base URL | —             |
    | `SECURITY_OAUTH2_REALM`           | OAuth2 realm name             | —             |
    | `SECURITY_OAUTH2_CLIENT_ID`       | OAuth2 client ID              | —             |

    #### SpiceDB authorization

    | Environment Variable  | Description             | Default Value |
    | --------------------- | ----------------------- | ------------- |
    | `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname | —             |
    | `FLOWX_SPICEDB_PORT`  | SpiceDB server port     | —             |
    | `FLOWX_SPICEDB_TOKEN` | SpiceDB API token       | —             |

    #### Organization manager

    | Environment Variable                               | Description                      | Default Value |
    | -------------------------------------------------- | -------------------------------- | ------------- |
    | `FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL` | Organization Manager service URL | —             |
  </Tab>

  <Tab title="Infrastructure">
    #### Qdrant (vector database)

    | Environment Variable              | Description                | Default Value |
    | --------------------------------- | -------------------------- | ------------- |
    | `QDRANT_CONNECTION_GRPC_ENDPOINT` | Qdrant gRPC endpoint       | —             |
    | `QDRANT_CONNECTION_API_KEY`       | Qdrant API key             | —             |
    | `QDRANT__CLUSTER__ENABLED`        | Enable Qdrant cluster mode | `true`        |

    #### Qdrant search tuning (knowledgebase-rag)

    These limits control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Both are read at request time, so a config change does not require a redeploy beyond the env-var rollout.

    | Environment Variable    | Description                                                                                                                                                      | Default Value |
    | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
    | `QDRANT_PREFETCH_LIMIT` | Maximum number of points returned by each dense/sparse prefetch stage in a hybrid search before fusion. Lower values reduce Qdrant memory pressure on large KBs. | `100`         |
    | `QDRANT_FUSION_LIMIT`   | Maximum number of points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker's input set.                     | `80`          |

    <Tip>
      Defaults are tuned for typical Knowledge Bases. Raise them only if recall is insufficient for very large or long-tailed KBs; lower them if you see Qdrant memory pressure or slow queries under filter-heavy workloads.
    </Tip>

    #### Planner (Qdrant seeding)

    | Environment Variable   | Description                                                                                                                | Default Value |
    | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------- |
    | `PLANNER_SEED_ENABLED` | When `true`, the `planner` service seeds its Qdrant benchmark collection on startup. Leave off unless seeding is required. | `false`       |

    #### Kafka

    | Environment Variable      | Description             | Default Value |
    | ------------------------- | ----------------------- | ------------- |
    | `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses  | —             |
    | `KAFKA_SECURITY_MODE`     | Kafka security protocol | `NONE`        |

    #### S3-compatible storage

    | Environment Variable                                | Description                           | Default Value |
    | --------------------------------------------------- | ------------------------------------- | ------------- |
    | `APPLICATION_FILE_STORAGE_S3_SERVER_URL`            | S3 endpoint URL                       | —             |
    | `APPLICATION_FILE_STORAGE_S3_ACCESS_KEY`            | S3 access key                         | —             |
    | `APPLICATION_FILE_STORAGE_S3_SECRET_KEY`            | S3 secret key                         | —             |
    | `APPLICATION_FILE_STORAGE_S3_BUCKET_NAME`           | S3 bucket name                        | —             |
    | `APPLICATION_FILE_STORAGE_S3_ROOT_DIRECTORY`        | Root directory within bucket          | —             |
    | `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET` | Auto-create bucket if missing         | `true`        |
    | `APPLICATION_FILE_STORAGE_ENABLED`                  | Enable file storage for conversations | `false`       |
  </Tab>

  <Tab title="AI models">
    <Info>
      LLM provider and model configuration lives in the **AI Providers** UI in FlowX Designer. Configure providers and models at the organization and workspace level rather than via per-service env vars.

      See the [AI providers and model configuration](/5.9/ai-platform/ai-providers) page for details.
    </Info>

    #### Organization manager connection

    All Python AI services require a connection to the Organization Manager to resolve LLM provider configuration:

    | Environment Variable                               | Description                                                | Default Value                    |
    | -------------------------------------------------- | ---------------------------------------------------------- | -------------------------------- |
    | `FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL` | Organization Manager service URL for LLM config resolution | `http://organization-manager:80` |

    These variables must be set on all Python services (Planner, AI Developer, AI Analyst, AI Designer, Agent Builder, Knowledgebase RAG, Embedder).
  </Tab>

  <Tab title="Observability">
    | Environment Variable  | Description                      | Default Value |
    | --------------------- | -------------------------------- | ------------- |
    | `FLOWX_OTEL_ENDPOINT` | OpenTelemetry Collector endpoint | —             |
    | `FLOWX_OTEL_DEBUG`    | Enable OTEL debug logging        | `false`       |

    #### Observatory integration (optional)

    | Environment Variable        | Description                        | Default Value |
    | --------------------------- | ---------------------------------- | ------------- |
    | `FLOWX_OBSERVATORY_API_URL` | Observatory API endpoint           | —             |
    | `FLOWX_OBSERVATORY_APP_ID`  | Observatory app identifier         | —             |
    | `FLOWX_OBSERVATORY_VERBOSE` | Enable verbose Observatory logging | `0`           |

    #### Debug logging

    | Environment Variable | Description            | Default Value |
    | -------------------- | ---------------------- | ------------- |
    | `VERBOSE`            | Enable verbose logging | `0`           |
  </Tab>

  <Tab title="Service endpoints">
    Override individual service endpoints using the `AI_SERVICE_<SERVICE_ID>_ENDPOINT` pattern:

    | Environment Variable                    | Target Service    | Default Port |
    | --------------------------------------- | ----------------- | ------------ |
    | `AI_SERVICE_PLANNER_ENDPOINT`           | Planner           | 9150         |
    | `AI_SERVICE_AI_DEVELOPER_ENDPOINT`      | AI Developer      | 9151         |
    | `AI_SERVICE_AI_ANALYST_ENDPOINT`        | AI Analyst        | 9152         |
    | `AI_SERVICE_AI_DESIGNER_ENDPOINT`       | AI Designer       | 9153         |
    | `AI_SERVICE_AGENT_BUILDER_ENDPOINT`     | Agent Builder     | 9154         |
    | `AI_SERVICE_KNOWLEDGEBASE_RAG_ENDPOINT` | Knowledgebase RAG | 9155         |

    **Example:**

    ```bash theme={"system"}
    AI_SERVICE_AGENT_BUILDER_ENDPOINT=host.docker.internal:9154
    ```

    <Info>
      When using Kubernetes service discovery (`GRPC_HOST_RESOLVER=k8s`), these overrides are typically not needed. Use them only for custom networking or mixed deployment scenarios.
    </Info>
  </Tab>
</Tabs>

***

## Agent Builder configuration

| Environment Variable           | Description                                                                   | Default Value |
| ------------------------------ | ----------------------------------------------------------------------------- | ------------- |
| `AGENT_BUILDER_MAX_TOOL_CALLS` | Maximum number of tool calls an agent can make in a single workflow execution | `20`          |

***

## Kafka topics

The AI Platform uses the following internal Kafka topics:

| Topic                                                              | Partitions | Purpose                                                            |
| ------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------ |
| `ai.flowx.ai-platform.knowledgebase.store-entry.index-request.v1`  | 1          | Indexing requests consumed by Knowledgebase Indexer v2             |
| `ai.flowx.ai-platform.knowledgebase.store-entry.index-response.v1` | 1          | Indexing results produced by Knowledgebase Indexer v2              |
| `ai.flowx.ai-platform.evals-judge.job.request.v1`                  | 3          | Judge job requests from `integration-designer` to `evals-judge`    |
| `ai.flowx.ai-platform.evals-judge.job.response.v1`                 | 3          | Scored responses from `evals-judge` back to `integration-designer` |
| `ai.flowx.ai-platform.evals-judge.job.dlq.v1`                      | 3          | Dead-letter queue for unscored judge jobs (manual operator review) |

<Info>
  For production environments, create these topics manually with appropriate replication factors. For development, Kafka auto-topic creation handles them automatically.
</Info>

***

## Deployment

<Tabs>
  <Tab title="Kubernetes (Helm)">
    The AI Platform ships as an umbrella Helm chart aggregating all microservices and infrastructure dependencies.

    **Install or upgrade:**

    ```bash theme={"system"}
    helm dependency update deployment/helm/ai-platform
    helm upgrade --install ai-platform deployment/helm/ai-platform \
      --set global.aiPlatformVersion=<version>
    ```

    **After deployment, initialize the platform:**

    ```bash theme={"system"}
    make initialize-platform
    ```

    #### Key Helm values

    **Replica counts:**

    | Service           | Default Replicas |
    | ----------------- | ---------------- |
    | Planner           | 2                |
    | AI Developer      | 2                |
    | AI Analyst        | 2                |
    | AI Designer       | 2                |
    | Agent Builder     | 2                |
    | Knowledgebase RAG | 2                |
    | Embedder          | 2                |

    **Global configuration:**

    ```yaml theme={"system"}
    global:
      flowx:
        idp:
          provider: keycloak
          keycloak:
            hostname: <your-keycloak-host>
            realm: <your-realm>
      telemetry:
        prometheus: enabled
        otelCollector: enabled
    ```
  </Tab>

  <Tab title="Docker Compose">
    <Warning>
      Docker Compose deployment is intended for **local development only**. Do not use it for production workloads.
    </Warning>

    ```bash theme={"system"}
    make run-in-docker AI_PLATFORM_VERSION=<version> AI_PLATFORM_ARCH=linux/arm64
    ```

    This starts all microservices plus infrastructure (Qdrant, MinIO, Kafka, monitoring stack).

    **Local Kubernetes (Kind):**

    ```bash theme={"system"}
    make run-in-k8s AI_PLATFORM_VERSION=<version>
    ```
  </Tab>
</Tabs>

***

## Storage requirements

| Component        | Default Persistent Volume  | Notes                          |
| ---------------- | -------------------------- | ------------------------------ |
| Qdrant data      | 30Gi                       | Vector embeddings              |
| Qdrant snapshots | 30Gi                       | Backup snapshots               |
| MinIO            | Distributed across 4 nodes | Configured per deployment      |
| Kafka            | 1Gi minimum                | Adjust based on message volume |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service discovery issues" icon="magnifying-glass">
    **Kubernetes DNS resolution:**

    ```bash theme={"system"}
    # Verify AI Platform services are running
    kubectl get services -l app=ai-platform

    # Check Helm deployment
    helm list -n ai-platform

    # Test DNS resolution
    nslookup ai-platform-ai-conversations.default.svc.cluster.local
    ```

    **Common causes:**

    * Incorrect `GRPC_HOST_RESOLVER_HELM_CHART` value
    * Services not in the same namespace
    * DNS not resolving due to CoreDNS issues
  </Accordion>

  <Accordion title="Database connectivity" icon="database">
    **Qdrant health check:**

    ```bash theme={"system"}
    curl http://<qdrant-host>:6333/healthz
    ```

    **Common causes:**

    * Missing `QDRANT_CONNECTION_API_KEY`
    * Qdrant cluster not fully initialized
  </Accordion>

  <Accordion title="Kafka connectivity" icon="bolt">
    **Verify broker availability:**

    ```bash theme={"system"}
    kafka-broker-api-versions --bootstrap-server <kafka-host>:9092
    ```

    **Verify topics exist:**

    ```bash theme={"system"}
    kafka-topics --bootstrap-server <kafka-host>:9092 --list | grep ai-platform
    ```

    **Common causes:**

    * Wrong `KAFKA_BOOTSTRAP_SERVERS` address
    * Topics not auto-created and not manually provisioned
    * Security mode mismatch (`KAFKA_SECURITY_MODE`)
  </Accordion>

  <Accordion title="Authentication problems" icon="shield-halved">
    **Verify Keycloak connectivity:**

    ```bash theme={"system"}
    curl https://<keycloak-host>/auth/realms/<realm>/.well-known/openid-configuration
    ```

    **Common causes:**

    * Incorrect `SECURITY_OAUTH2_BASE_SERVER_URL`
    * Realm name mismatch
    * Client ID not registered in Keycloak
    * SpiceDB token expired or misconfigured
  </Accordion>

  <Accordion title="AI model configuration errors" icon="robot">
    If AI nodes fail with model-related errors:

    * Verify that an AI provider is configured at **Organization Settings** → **AI Settings** → **Model Providers** with a successful connection test
    * Check that models are enabled in the provider's whitelist
    * Verify that workspace-type model assignments are set for the relevant AI capability (text generation, image understanding, embeddings, document/OCR) under **AI Settings** → **Defaults & Fallbacks**
    * Ensure `FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL` is set on all Python AI services and points to a reachable Organization Manager instance

    See the [AI providers and model configuration](/5.9/ai-platform/ai-providers) page for setup details.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="AI in FlowX" icon="brain" href="./ai-in-flowx">
    Overview of config-time and business AI agents
  </Card>

  <Card title="Agent Builder" icon="wand-magic-sparkles" href="./agent-builder/overview">
    Build custom AI agents with the no-code agent builder
  </Card>

  <Card title="Deployment guidelines v5.9" icon="rocket" href="/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9">
    Component versions and upgrade instructions
  </Card>
</CardGroup>


# AI providers and model configuration
Source: https://docs.flowx.ai/5.9/ai-platform/ai-providers

Configure AI providers and assign default and fallback models per workspace type for text generation, image understanding, embeddings, and document processing.

## Overview

FlowX supports configuring AI providers at three levels:

* **Organization level**: Add and manage AI providers, set API keys, whitelist specific models
* **Organization level (per workspace type)**: Assign default and fallback models for each AI capability, scoped by workspace type (Sandbox, Staging, Production)
* **Node level**: Override the default model on individual workflow nodes

Organization admins define which providers and models are available, and configure model assignments per workspace type. Workflow designers can optionally override the model on individual AI nodes.

***

## Organization-level: Model providers

Access model providers from **Organization Settings** → **AI Settings** → **Model Providers**.

<Frame>
  ![Model Providers page in Organization Settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_org_settings.png)
</Frame>

An **OpenAI** provider card is present by default, using a FlowX-managed key. You can switch it to your own key or add additional providers.

### Adding a provider

<Steps>
  <Step title="Navigate to Model Providers">
    In FlowX Designer, go to your organization settings and select **Model Providers**.
  </Step>

  <Step title="Add a provider">
    Click the **+** button to open the **Provider Details** dialog. Configure:

    | Field               | Description                                                                                                                       |
    | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | **Provider**        | Select from the provider catalog (e.g., OpenAI)                                                                                   |
    | **Base URL**        | API endpoint (required). OpenAI offers presets (Global, EU, US) or select **Custom URL** to enter any OpenAI-compatible endpoint. |
    | **API Key Source**  | Select **Own** to provide your own API key, or **FlowX** to use the FlowX-provided API key                                        |
    | **Key**             | Your provider API key (required, shown when **Own** is selected)                                                                  |
    | **Organization ID** | Provider organization ID (optional)                                                                                               |

    <Note>
      You cannot add the same provider type twice. The system validates against the provider catalog and shows an error if a duplicate is attempted.
    </Note>
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to validate your credentials against the provider API.

    * **Success:** "Connection successful. X models discovered."
    * **Failure:** Error details are shown (e.g., invalid API key for 401, insufficient permissions for 403).

    You cannot save the provider configuration until the connection test succeeds.
  </Step>

  <Step title="Enable models">
    After saving, click **Manage Models** to open the model whitelisting modal. Enable specific models from the discovered list. Only enabled models appear in workspace-type assignments (Sandbox, Staging, Production).
  </Step>
</Steps>

### API Key Source

The **API Key Source** radio buttons control how the provider authenticates:

| Option    | Description                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| **Own**   | Provide your own API Key. You have full control over the key, Organization ID, and which models are enabled. |
| **FlowX** | Use the FlowX-provided API key. The Key and Organization ID fields are hidden and cannot be edited.          |

When editing the OpenAI provider, switch between **Own** and **FlowX** under API Key Source.

### Model whitelisting

The model whitelisting modal (opened from **Manage Models**) lets you control which discovered models are available downstream. Models are grouped by capability:

| Category            | Description                                                | Example models                                 |
| ------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| **Text Generation** | Text responses, summaries, translations, extraction        | gpt-4o, gpt-4o-mini, gpt-4-turbo               |
| **Code Generation** | Automated code generation for Developer Agents             | gpt-4o, gpt-4o-mini                            |
| **Embeddings**      | Vector representations for knowledge base indexing and RAG | text-embedding-3-large, text-embedding-3-small |
| **Speech to Text**  | Audio transcription for the Speech to Text workflow node   | whisper-1                                      |

Each model row shows: model name, capability badges, context window (e.g., "128K tokens"), and indicative pricing (e.g., "$5 / $15 per 1M tokens").

* Use **Search** to filter models by name
* Use **Select All** / **Deselect All** for bulk actions
* A counter at the bottom shows "X of Y models enabled"
* Click **Save Whitelist** to persist your selection

<Warning>
  Disabling a previously enabled model shows a warning listing where that model is currently used (workspace defaults, fallback assignments). Disabling it causes affected configurations to fall back to their fallback model.
</Warning>

<Note>
  Model whitelisting is not available when using the FlowX-managed key for OpenAI.
</Note>

### Editing a provider

When editing an existing provider (API key or Organization ID changed):

1. The **Save** button is disabled after any field edit
2. Click **Test Connection** to validate the new credentials
3. On success, **Save** becomes enabled
4. If the newly discovered model list differs from the previous one:
   * New models are added to the whitelist automatically
   * If any previously enabled models are no longer available, a replacement wizard guides you through selecting alternatives
   * Skipping the wizard removes the missing models from all dropdowns where they were used, and the fallback mechanism activates

### Deleting a provider

All providers except the default OpenAI (FlowX-managed) can be deleted. Deleting a provider:

1. Shows a confirmation with the impact: nodes and knowledge bases using this provider's models switch to their fallback model
2. If the fallback model is also from the deleted provider, a warning indicates that all LLM-related activities using those models will fail

### Provider card

Each provider card shows:

* Provider name and icon
* Masked API key (last 4 characters visible, e.g., `••••••••••••1234`)
* Model count: "Models enabled: X / Y"
* Organization ID (if configured)
* Connection status
* Available actions: **Manage Models**, **Edit**, **Delete**

***

## Defaults & Fallbacks

Access model assignments from **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**.

<Frame>
  ![Defaults & Fallbacks configuration with workspace-type tabs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/workspace_level.png)
</Frame>

Organization admins assign a **Default Model** and an optional **Fallback Model** for each AI capability, scoped by **workspace type**. Use the **Sandbox**, **Staging**, and **Production** tabs to configure different model assignments per environment. Select **Use provider default** to inherit the catalog default for that capability.

| Capability              | Used for                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text Generation**     | Text operations (summarization, translation, extraction), data operations (enrichment, generation, transformation), custom agents, and intent classification                                                                          |
| **Image Understanding** | AI image nodes — image description and image analysis. Only models with vision capability are shown.                                                                                                                                  |
| **Embeddings**          | Knowledge base indexing and context retrieval (RAG). Used by context retrieval nodes in workflows.                                                                                                                                    |
| **Document / OCR**      | AI document nodes — document generation, extraction, understanding, and text extraction from documents.                                                                                                                               |
| **Developer Agents**    | AI planner, developer, analyst, and designer agents. Used for automated code generation and analysis workflows. For best performance, this capability uses the FlowX tested and optimized model configured at the organization level. |
| **Audio Capabilities**  | Speech-to-text transcription. Used by the Speech to Text workflow node.                                                                                                                                                               |

Default models from the OpenAI FlowX key are pre-assigned for each capability.

### Assigning models

For each capability:

1. Select a **Default model** from org-whitelisted models matching that capability, or use the **provider default**
2. Optionally select a **Fallback model**, used if the default model is unavailable or rate-limited

Assignments are configured per workspace type (Sandbox, Staging, Production). All workspaces of a given type inherit the same model assignments.

<Warning>
  If the default and fallback models use the same provider, a warning is displayed. Using different providers for default and fallback improves resilience against provider outages.
</Warning>

<Note>
  When **Use provider default** is selected, the assignment inherits the catalog default model. Changes to the catalog default automatically propagate.
</Note>

***

## Fallback behavior

When a primary model is unavailable, rate-limited, or disabled at the organization level, the system automatically switches to the configured fallback model. The resolution order is:

1. **Node-level override** (if configured) → its fallback model
2. **Workspace default** → its fallback model
3. **Error** if all options exhausted

| Scenario                              | Behavior                                                                                                                                 |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Primary model unavailable             | Fallback model is used automatically                                                                                                     |
| Node override model not found         | Falls back to workspace default model                                                                                                    |
| API key expired or revoked            | Nodes using this provider's models fail with "API key invalid" in the execution log. Provider shows a warning at the organization level. |
| Both primary and fallback unavailable | Node fails with error: "Primary and fallback models unavailable. Contact your organization admin."                                       |

***

## Per-node model override

Workflow designers can override the default model on individual AI nodes (Custom Agent, Intent Classification, etc.) in the Integration Designer. This allows different nodes in the same workflow to use different models. For example, a fast model for intent classification and a more capable model for complex reasoning.

<Frame>
  ![Per-node model override in Integration Designer workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/node_level.png)
</Frame>

### How it works

When configuring an AI node, an optional **Model Override** section lets you select a specific model:

| Field                      | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| **Provider type**          | The provider to use (e.g., `OPENAI`)                     |
| **Model**                  | The specific model (e.g., `gpt-4o`)                      |
| **Fallback provider type** | Optional fallback provider if the primary is unavailable |
| **Fallback model**         | Optional fallback model                                  |

The override uses portable identifiers (`providerType` + `modelIdStr`) that resolve at runtime against the organization's available models. Only models enabled in the organization's whitelist can be selected.

When no override is set, the node uses the workspace default model for its capability (text generation, embeddings, etc.).

<Info>
  Per-node model overrides apply to the **text generation** capability only. Other capabilities (image understanding, embeddings, document/OCR) always use the workspace defaults.
</Info>

***

## Supported providers

FlowX maintains a provider catalog with pre-configured provider types. Each provider type includes display metadata (name, icon) and optional base URL presets.

| Provider   | Key mode              | Notes                               |
| ---------- | --------------------- | ----------------------------------- |
| **OpenAI** | FlowX Managed or BYOK | EU, US, and Global base URL presets |

***

## Permissions

| Permission              | Description                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `org_ai_providers_read` | View AI providers and model assignments at organization level                            |
| `org_ai_providers_edit` | Add, edit, delete providers, manage model whitelists, and configure Defaults & Fallbacks |

***

## Related resources

<CardGroup>
  <Card title="AI in FlowX" icon="brain" href="./ai-in-flowx">
    Overview of AI capabilities in the FlowX platform
  </Card>

  <Card title="Agent Builder" icon="hammer" href="./agent-builder/overview">
    Build AI agents that use the configured models
  </Card>

  <Card title="Conversational Workflows" icon="comments" href="./conversational-workflows">
    Create chat experiences powered by AI models
  </Card>

  <Card title="Organization Settings" icon="building" href="/5.9/docs/saas/organization-settings">
    Manage organization-level settings
  </Card>
</CardGroup>


# Chat component
Source: https://docs.flowx.ai/5.9/ai-platform/chat-component

Technical reference for the Chat component - runtime behavior, session management, workflows, and SDK integration.

The Chat component enables interactive AI agent conversations with end-users within FlowX apps. This page covers runtime behavior, session management, and advanced integration patterns.

<Frame>
  <video />
</Frame>

<Info>
  For UI configuration, settings, and styling, see the [Chat component in UI Designer](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat).
</Info>

## Key features

<CardGroup>
  <Card title="Real-time messaging" icon="bolt">
    Send and receive messages instantly with streaming support
  </Card>

  <Card title="AI agent integration" icon="robot">
    Connect to workflows powered by AI agents
  </Card>

  <Card title="Session management" icon="id-badge">
    Automatic session handling and persistence across page refreshes
  </Card>

  <Card title="Message history" icon="clock-rotate-left">
    Retrieve and display conversation history on refresh
  </Card>

  <Card title="Knowledge Base integration" icon="database">
    Ground AI responses in your organization's data using RAG capabilities
  </Card>

  <Card title="Reasoning transparency" icon="brain">
    Show AI reasoning steps to users for trust and transparency
  </Card>

  <Card title="Flexible display modes" icon="layout">
    Inline, Overlay, FullScreen, and Floating modes with per-mode theming for Web, Android, and iOS
  </Card>
</CardGroup>

***

## Display modes

<Info>
  The Chat component supports four distinct display modes, including mobile chat support.
</Info>

When adding a Chat component, you choose a **display mode** that determines how the chat renders and behaves at runtime.

| Display mode   | Description                                                | Placement                      |
| -------------- | ---------------------------------------------------------- | ------------------------------ |
| **Inline**     | Renders in place within the page layout (default)          | Child of any container or card |
| **Overlay**    | Positioned overlay panel with minimize and expand controls | Child of Page or Root Zone     |
| **FullScreen** | Takes over the full viewport                               | Child of Page or Root Zone     |
| **Floating**   | Floating panel triggered by a FAB (Floating Action Button) | Child of Page or Root Zone     |

<Info>
  You can change the display mode after creation if needed.
</Info>

### Mode details

<Tabs>
  <Tab title="Inline">
    Renders within the parent component, filling the available space. This is the default mode.

    * Can be a child of **any container or card**
    * Embeds directly into the page layout
    * Best for dedicated chat pages or inline chat experiences
    * Width and height follow the parent container; supports **Fill** or **Fixed** sizing
  </Tab>

  <Tab title="Overlay">
    Renders as a positioned panel on top of the page content, with controls to minimize or expand.

    * Must be a child of **Page** or **Root Zone** (global scope)
    * Includes minimize and expand buttons in the chat header
    * Useful when the chat should be accessible without leaving the current page context
  </Tab>

  <Tab title="FullScreen">
    Takes over the full viewport when opened.

    * Must be a child of **Page** or **Root Zone**
    * Provides an immersive, distraction-free chat experience
    * Triggered via the chat header button or a FAB
    * Automatically dismissed when the user closes or navigates away
  </Tab>

  <Tab title="Floating">
    Renders as a floating panel anchored to a corner of the screen. Triggered by a **Floating Action Button (FAB)**.

    * Must be a child of **Page** or **Root Zone**
    * FAB defaults to bottom-right position (`right: 24px`, `bottom: 24px`)
    * FAB dimensions: `56 × 56px` (configurable)
    * Chat panel defaults: `420px` wide, `640px` tall
    * Best for persistent, always-accessible chat without interrupting main content
  </Tab>
</Tabs>

### Sizing defaults

| Display mode   | Default width   | Default height  | Notes                                |
| -------------- | --------------- | --------------- | ------------------------------------ |
| **Inline**     | Fill (parent)   | Fill (parent)   | Supports Fill or Fixed sizing        |
| **Overlay**    | Configurable    | Configurable    | Positioned over content              |
| **FullScreen** | Full viewport   | Full viewport   | No sizing controls                   |
| **Floating**   | `420px` (fixed) | `640px` (fixed) | FAB at `right: 24px`, `bottom: 24px` |

### Theming per display mode

Theme values can be set independently for each display mode and per platform (Web, Android, iOS) through **Design Assets** → **Themes** → **Components** → **Chat**.

| Platform    | Configurable modes           |
| ----------- | ---------------------------- |
| **Web**     | Inline, Floating, FullScreen |
| **Android** | Inline, Floating, FullScreen |
| **iOS**     | Inline, Floating, FullScreen |

Each mode supports independent configuration for padding, margin, and other layout tokens.

### Chat header button and URL synchronization

The chat header includes a state-aware button that adapts based on the current display mode (for example, toggling between fullscreen and overlay views). Chat session state is also synchronized to the browser URL via `popstate`, so navigating back or refreshing the page restores the correct session context.

### Global component

The Chat component can be added as a **Global Component** in UI Flows, making it persist across pages without needing to add it to each page individually.

When configured as a global component:

* The chat appears in the **Global Components** section of the left navigation panel
* It persists as users navigate between pages in the UI Flow
* You can **attach** or **detach** the chat from specific pages to control where it appears
* The chat maintains its conversation state across page navigation

To add Chat as a global component, click **+** in the **Global Components** section of the UI Flow navigation panel, then select **Chat** and configure its display mode.

<Tip>
  Use Global Components when you want the chat to be available throughout the entire app experience without re-adding it to every page.
</Tip>

### Sizing

The Chat component and floating action button support **fixed sizing**, allowing you to set a specific width and/or height value for precise control over the chat container dimensions.

***

## Subcomponents

<Info>
  The Chat component includes specialized subcomponents for reasoning display, error handling, and message regeneration.
</Info>

The Chat component is composed of the following subcomponents:

| Subcomponent          | Description                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Header**            | Configurable header with avatar, title, subtitle, new chat button, fullscreen toggle, and dock/collapse controls                         |
| **Messages**          | Message display with sender/receiver differentiation, markdown rendering, and avatar support                                             |
| **Chat History**      | Conversation history list showing past chat sessions grouped by time, with the ability to resume previous conversations                  |
| **Suggested Prompts** | Pre-configured prompt suggestions displayed before the user types, allowing quick-start interactions                                     |
| **Reasoning**         | Displays AI reasoning steps (thinking indicators) during response generation                                                             |
| **Input**             | Message input field with configurable placeholder and multiline support. Includes a Stop button to cancel an in-progress agent response. |

### Reasoning display

The reasoning subcomponent shows users how the AI agent is processing their request. When enabled, a thinking indicator appears while the agent works through its reasoning steps.

| Property            | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| **reasoning**       | Toggle to show/hide reasoning steps in the chat                  |
| **thinkingMessage** | Custom message to display during reasoning (e.g., "Thinking...") |

### Error handling and regeneration

When a message fails to generate, the chat displays an error state with an option to retry:

| Property            | Description                                     |
| ------------------- | ----------------------------------------------- |
| **errorMessage**    | Custom error message to display on failure      |
| **canRegenerate**   | Enable the regenerate button on failed messages |
| **regenerateLabel** | Custom label for the regenerate button          |

### Chat History

Chat History displays a list of conversations started by the current user, grouped by time period: **Today**, **Yesterday**, **Previous 7 Days**, **Previous 30 Days**, and **Older**.

<Frame>
  ![Chat History panel showing past conversations grouped by time](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
</Frame>

#### Behavior

* The chat history button is always visible in the chat header
* When opened, the list shows each conversation with its title and timestamp (displayed in a tooltip)
* Available actions: **New chat**, **Expand/Minimize**, **Dock** (hide chat)
* Opening a conversation from the list resumes the session:
  * Messages are prefilled with the last exchanged messages
  * Scrolling up loads older replies
  * New messages continue on the same session ID
* Conversations are **per-user** — attempting to access another user's history shows an access denied error and redirects to a new chat session

#### Theming

Chat History adds three new themed elements configurable per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through **Design Assets** → **Themes** → **Components** → **Chat**:

| Theme element            | Description                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| **Chat History**         | Container for the conversation list (padding, empty state font/color, gap)                      |
| **Chat History Section** | Time-group headers like "Today" or "Previous 7 Days" (title font/color, gap)                    |
| **Chat History Item**    | Individual conversation entry with hover state (padding, font, border radius, background color) |

Two new system icons are added: `sys_ChatHistory` and `sys_ChatBack`.

#### Localization

Chat History uses system substitution tags for all labels. Override these in **CMS** → **Substitution Tags** to customize or localize:

| Substitution tag                       | Default (EN)                                              |
| -------------------------------------- | --------------------------------------------------------- |
| `sys_chat_tooltip_chat_history`        | Chat History                                              |
| `sys_chat_tooltip_new_chat`            | New chat                                                  |
| `sys_chat_tooltip_expand`              | Expand                                                    |
| `sys_chat_tooltip_minimize`            | Exit full screen                                          |
| `sys_chat_tooltip_dock`                | Hide chat                                                 |
| `sys_chat_tooltip_back`                | Back                                                      |
| `sys_chat_time_group_today`            | Today                                                     |
| `sys_chat_time_group_yesterday`        | Yesterday                                                 |
| `sys_chat_time_group_previous_7_days`  | Previous 7 Days                                           |
| `sys_chat_time_group_previous_30_days` | Previous 30 Days                                          |
| `sys_chat_time_group_older`            | Older                                                     |
| `sys_chat_conversations_empty_state`   | No Conversations yet                                      |
| `sys_chat_forbidden`                   | Access denied. This chat history belongs to another user. |

***

### Markdown rendering in messages

Agent (receiver) messages support Markdown formatting, allowing AI-generated responses to include structured content. The renderer automatically converts Markdown syntax to styled HTML.

**Supported syntax:**

| Syntax                               | Renders as                     |
| ------------------------------------ | ------------------------------ |
| `**bold**`                           | **Bold** text                  |
| `*italic*`                           | *Italic* text                  |
| `# Heading` through `###### Heading` | Heading levels 1–6             |
| `` `inline code` ``                  | Inline code                    |
| ` ``` code block ``` `               | Fenced code block              |
| `- item` or `1. item`                | Unordered and ordered lists    |
| `[text](url)`                        | Hyperlink (opens in a new tab) |
| Single newline                       | Line break (`<br/>`)           |

<Tip>
  When building AI agent prompts, you can instruct the agent to format responses using Markdown — the chat component renders the output automatically.
</Tip>

***

### Suggested Prompts

The Suggested Prompts subcomponent displays a set of pre-configured prompt suggestions to the user before they begin typing. When a suggestion is clicked, its text is sent as the user's input, starting the conversation immediately.

<Frame>
  ![Suggested Prompts displayed in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
</Frame>

#### Props

| Property  | Type      | Default               | Description                                       |
| --------- | --------- | --------------------- | ------------------------------------------------- |
| `title`   | string    | `"Suggested Prompts"` | Section heading displayed above the prompt list   |
| `prompts` | string\[] | —                     | Array of prompt strings to display as suggestions |

#### Behavior

* The subcomponent only renders when at least one prompt is provided in the `prompts` array. If the array is empty or not set, the section is hidden entirely.
* Clicking a suggestion sends that prompt text as the user's input, triggering the chat workflow as if the user typed and submitted the message.
* Long prompt strings that exceed the display area are truncated and shown in full via a **tooltip** on hover.

#### Theming

Full theming support is available in both Angular and React SDKs. Styles can be configured per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through Theme Admin (**Design Assets** → **Themes** → **Components** → **Chat** → **Suggested Prompts**).

<Tip>
  Use suggested prompts to guide users toward the most common questions or actions in your chat experience. Keep individual prompts short and action-oriented so they remain readable without truncation.
</Tip>

#### AI-generated prompt suggestions

In addition to the static suggested prompts configured above, the chat component can display **AI-generated prompt suggestions** that are dynamically created by Custom Agent nodes in conversational workflows.

When a Custom Agent node has **Prompt Suggestions** enabled (via its satellite panel), the agent generates contextual follow-up suggestions alongside each reply. These appear as clickable chips below the agent's message, similar to static suggested prompts but tailored to the conversation context.

**Key differences from static suggested prompts:**

|                   | Static suggested prompts         | AI-generated suggestions                         |
| ----------------- | -------------------------------- | ------------------------------------------------ |
| **Source**        | Configured on the chat component | Generated by Custom Agent node per reply         |
| **When shown**    | Empty state or as configured     | After each agent reply that includes suggestions |
| **Content**       | Fixed text                       | Dynamic, context-aware                           |
| **Configuration** | Chat component settings          | Custom Agent node satellite panel                |

When a user clicks an AI-generated suggestion, the chip's `label` is displayed as the user's message while the full `content` is sent as input to the next workflow run.

For configuration details, see the [Custom Agent node documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions).

***

### Voice input

Users can send voice messages in addition to typed text. When voice input is enabled, a microphone button appears in the chat input. Clicking it records audio in the browser; the recording is uploaded and sent as the user's next message, appearing in the chat history as an audio player alongside text messages.

#### Enabling voice input

Voice input is configured on the **Chat Input** sub-component in UI Designer:

| Property               | Description                                    | Default |
| ---------------------- | ---------------------------------------------- | ------- |
| **Enable Voice Input** | Toggle the microphone button in the chat input | `Off`   |

When enabled, the microphone button is shown by default, the SDK handles recording, upload, and playback, and the agent receives the audio file as part of the message payload. To transcribe incoming audio or generate spoken replies from the agent side, combine voice input with the [Speech to Text node](/5.9/ai-platform/agent-builder/speech-to-text).

#### Runtime behavior

* **Recording limit:** 2 minutes per message. Longer recordings stop automatically.
* **Blocked during replies:** The microphone is disabled while the agent is streaming a response (SSE in progress) to prevent interleaved turns.
* **Single player:** Only one audio message can play at a time — starting a new playback pauses any other voice message.
* **History:** Voice messages are persisted with the rest of the conversation and replayed with a progress bar when the user scrolls back.

***

### Stop agent response

When the user presses Stop:

* The running conversational workflow is cancelled. If cancellation happens before any AI node executes, the user prompt is persisted as cancelled and no AI call is made. If it happens while an AI node is executing, the in-flight AI call is stopped and any partial response is discarded.
* The chat receives a `chatCancelled` SSE event on the `CHAT_WORKFLOW_RESPONSE` channel, signalling the UI to exit the streaming state.
* The user message is stored with a `cancelled: true` flag on the chat message record.

Stop is supported on Web (Standard, Floating, Full Screen), iOS, and Android.

For details on the underlying workflow cancel API and pre-AI vs during-AI behavior, see [Cancelling a running workflow](/5.9/ai-platform/conversational-workflows#cancelling-a-running-workflow).

#### Theming

The Stop button uses a system icon registered as `stopResponseIcon` under each chat input area. Defaults preloaded by `cms-core`:

| Theme content                                                             | Property           | Default value          |
| ------------------------------------------------------------------------- | ------------------ | ---------------------- |
| `chatInputArea`, `chatInputAreaFloating`, `chatInputAreaFullScreen` (Web) | `stopResponseIcon` | `sys_ChatStopResponse` |
| `chatInputArea` (iOS)                                                     | `stopResponseIcon` | `sys_ChatStopResponse` |
| `chatInputArea` (Android)                                                 | `stopResponseIcon` | `sys_ChatStopResponse` |

Override `stopResponseIcon` in the active theme to swap the icon, the same way you would override `sendMessageIcon` or `voiceInputIcon`.

#### Localization

The chat input action labels are configurable via system substitution tags. The `a11y` variants are used as accessibility labels (screen reader text); the non-`a11y` variants are used as visible labels and tooltips.

| Substitution tag               | Purpose                         | Default English value    |
| ------------------------------ | ------------------------------- | ------------------------ |
| `sys_chat_cancel_request`      | Stop button label               | Stop generating response |
| `sys_a11y_chat_cancel_request` | Stop button accessibility label | Stop generating response |
| `sys_chat_submit_message`      | Send button label               | Send message             |
| `sys_a11y_chat_submit_message` | Send button accessibility label | Send message             |

***

### Chat configuration

The `chatConfig` object controls the behavior and appearance of the chat:

| Property           | Type    | Description                                    |
| ------------------ | ------- | ---------------------------------------------- |
| `welcomeMessage`   | string  | Initial message shown when the chat opens      |
| `thinkingMessage`  | string  | Message displayed during AI reasoning          |
| `title`            | string  | Header title text                              |
| `subtitle`         | string  | Header subtitle text                           |
| `showChatIcon`     | boolean | Show/hide the chat icon                        |
| `showSeparator`    | boolean | Show/hide the separator between messages       |
| `newChatLabel`     | string  | Label for the new chat button                  |
| `errorMessage`     | string  | Message shown on errors                        |
| `canRegenerate`    | boolean | Enable message regeneration on failure         |
| `regenerateLabel`  | string  | Label for the regenerate button                |
| `inputPlaceholder` | string  | Placeholder text for the input field           |
| `maxInputRows`     | number  | Maximum number of rows for multiline input     |
| `historyTitle`     | string  | Title text displayed on the chat history panel |

***

## Runtime behavior

### Starting a chat

<Steps>
  <Step title="User initiates chat">
    User opens the chat from the UI Flow
  </Step>

  <Step title="API call">
    System calls the start chat API with the configured workflow
  </Step>

  <Step title="Session created">
    API returns a `chatSessionId` that is persisted for the user
  </Step>

  <Step title="Initial message">
    First message typically comes from the AI agent as a greeting or conversation starter
  </Step>
</Steps>

<Info>
  The initial system message can be configured in the workflow to provide a customized greeting or conversation starter.
</Info>

### Message exchange

<Tabs>
  <Tab title="Sending messages">
    1. User types message in input field
    2. Message is sent to the workflow via Chat Input node
    3. Workflow processes the message through AI nodes
    4. Response is returned to the chat interface
  </Tab>

  <Tab title="Receiving messages">
    * Messages appear in real-time with streaming support
    * User messages aligned to one side
    * Agent messages aligned to the other side
    * Timestamps displayed (configurable)
  </Tab>
</Tabs>

### Session management

<CardGroup>
  <Card title="Session persistence" icon="database">
    * `sessionId` stored in browser session/local storage
    * Enables conversation continuity across page refreshes
    * Session data includes message history
  </Card>

  <Card title="Message history retrieval" icon="rotate">
    * On page refresh, system loads existing `sessionId`
    * Retrieves and displays previous messages
    * Restores conversation state automatically
  </Card>
</CardGroup>

### Data storage

Chat sessions are persisted in the **FlowX Database**:

<Info>
  Each chat session is stored as a **document** containing the complete chat history. The chat component works with the FlowX Database to save chat sessions, where each session document contains the full conversation record.
</Info>

| Data Element         | Storage Location           | Description                                             |
| -------------------- | -------------------------- | ------------------------------------------------------- |
| **Session ID**       | Browser storage + Database | Unique identifier linking client to server-side session |
| **Message history**  | FlowX Database             | Complete record of all messages in the conversation     |
| **Session metadata** | FlowX Database             | Timestamps, workflow reference, user information        |

<Tip>
  **Transparent persistence**: Message persistence to the database is handled transparently by the platform. No additional configuration is required to enable chat history storage.
</Tip>

***

## Conversation history API

FlowX provides REST API endpoints for retrieving conversation history programmatically. These are useful for building custom dashboards, analytics, or integrating conversation data into external systems.

### List conversations

Retrieve all conversations for the current authenticated user within a workspace and app.

```bash theme={"system"}
GET /api/runtime/wks/{workspaceId}/app/{appId}/conversations
```

**Path parameters:**

| Parameter     | Type | Description              |
| ------------- | ---- | ------------------------ |
| `workspaceId` | UUID | The workspace identifier |
| `appId`       | UUID | The app identifier       |

**Query parameters (optional):**

| Parameter        | Type               | Description                                   |
| ---------------- | ------------------ | --------------------------------------------- |
| `startDate`      | ISO 8601 timestamp | Filter conversations created after this date  |
| `endDate`        | ISO 8601 timestamp | Filter conversations created before this date |
| `businessCaseId` | UUID               | Filter by business case identifier            |
| `page`           | integer            | Page number for pagination                    |
| `size`           | integer            | Number of conversations per page              |

**Response:**

```json theme={"system"}
{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "state": "ACTIVE",
      "createdAt": "2026-03-10T14:30:00Z",
      "summary": "Customer asked about account verification process",
      "messageCount": 12
    }
  ],
  "total": 1
}
```

### Fetch a single conversation

Retrieve a single conversation with its full message history.

```bash theme={"system"}
GET /api/runtime/wks/{workspaceId}/app/{appId}/conversations/{conversationId}
```

**Path parameters:**

| Parameter        | Type | Description                                |
| ---------------- | ---- | ------------------------------------------ |
| `workspaceId`    | UUID | The workspace identifier                   |
| `appId`          | UUID | The app identifier                         |
| `conversationId` | UUID | The conversation (chat session) identifier |

**Query parameters (optional):**

| Parameter | Type    | Description                        |
| --------- | ------- | ---------------------------------- |
| `page`    | integer | Page number for message pagination |
| `size`    | integer | Number of messages per page        |

**Response:**

```json theme={"system"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "ACTIVE",
  "summary": "Customer asked about account verification process",
  "createdAt": "2026-03-10T14:30:00Z",
  "userEmail": "user@example.com",
  "messages": [
    {
      "actor": "human",
      "message": "How do I verify my account?",
      "timestamp": "2026-03-10T14:30:05Z",
      "messageId": "msg-001"
    },
    {
      "actor": "agent",
      "message": "To verify your account, navigate to **Settings** → **Verification**...",
      "timestamp": "2026-03-10T14:30:08Z",
      "messageId": "msg-002"
    }
  ],
  "total": 2
}
```

**Error responses:**

| Status | Description                                    |
| ------ | ---------------------------------------------- |
| `404`  | Conversation not found                         |
| `403`  | User does not have access to this conversation |

<Info>
  These endpoints return conversations owned by the authenticated user only. The workspace must belong to the user's organization.
</Info>

***

## Custom chat persistence workflow

For advanced use cases where you need full control over chat session storage, you can build a custom workflow that manages chat persistence using FlowX Database. This approach allows you to:

* Customize the chat data model
* Add additional metadata to chat sessions
* Integrate with external systems
* Implement custom session management logic

### Workflow overview

The chat persistence workflow handles two main scenarios:

1. **Loading chat history** - When a user returns to an existing chat session
2. **Processing new messages** - When a user sends a new message

```mermaid theme={"system"}
flowchart TD
    A[Start] --> B[Get chat session]
    B --> C{Action type?}
    C -->|LOAD_HISTORY| D[Return chat history]
    C -->|NEW_MESSAGE| E{Session exists?}
    E -->|No| F[Create new session]
    E -->|Yes| G[Update session history]
    F --> H[Return response]
    G --> I[Update chat session]
    I --> H
```

### Setting up the FlowX database data source

<Steps>
  <Step title="Create the data source">
    Navigate to **Integrations** → **Data Sources** → **Add New Data Source** and select **FlowX Database**.
  </Step>

  <Step title="Configure the collection">
    Name the collection (e.g., `chat`) and define the schema based on your data model.
  </Step>

  <Step title="Define the data model">
    Create a data model with the following structure:

    | Field               | Type   | Description                            |
    | ------------------- | ------ | -------------------------------------- |
    | `chatSessionId`     | string | Unique identifier for the chat session |
    | `history`           | array  | List of message objects                |
    | `history[].actor`   | string | Message sender (`human` or `agent`)    |
    | `history[].message` | string | The message content                    |
  </Step>
</Steps>

### Building the workflow

<Steps>
  <Step title="Create the workflow">
    Create a new workflow in Integration Designer with the following input parameters:

    ```json theme={"system"}
    {
      "humanMessage": "",
      "action": "",
      "chatSessionId": ""
    }
    ```

    The `action` parameter determines whether to load history (`LOAD_HISTORY`) or process a new message.
  </Step>

  <Step title="Add Get chat session node">
    Add a **Database Operation** node to retrieve the existing session:

    | Property                     | Value                |
    | ---------------------------- | -------------------- |
    | **Operation**                | `db.chat.findOne`    |
    | **Description**              | Chat session history |
    | **Parameter: chatSessionId** | `${chatSessionId}`   |
    | **Response Key**             | `chatSession`        |
  </Step>

  <Step title="Add action type condition">
    Add a **Condition** node to check the action type:

    ```javascript theme={"system"}
    input.action == "LOAD_HISTORY"
    ```

    * **If true**: Route to the "Return chat history" end node
    * **Else**: Continue to message processing
  </Step>

  <Step title="Add Return chat history end node">
    For the `LOAD_HISTORY` branch, add an **End Flow** node that returns the chat history:

    ```json theme={"system"}
    {
      "history": "${chatSession.data.history}"
    }
    ```
  </Step>

  <Step title="Add session exists condition">
    For new messages, add another **Condition** node to check if the session exists:

    ```javascript theme={"system"}
    input.chatSession.data == null
    ```
  </Step>

  <Step title="Add Create chat session node">
    If the session doesn't exist, add a **Database Operation** node to create it:

    | Property                     | Value                                                  |
    | ---------------------------- | ------------------------------------------------------ |
    | **Operation**                | `db.chat.insertOne`                                    |
    | **Description**              | Create chat session                                    |
    | **Parameter: chatSessionId** | `${chatSessionId}`                                     |
    | **Parameter: history**       | `[{ "actor": "human", "message": "${humanMessage}" }]` |
    | **Response Key**             | `responseKey`                                          |
  </Step>

  <Step title="Add Update history script node">
    If the session exists, add a **Script** node to append the new messages:

    ```javascript theme={"system"}
    const history = input.chatSession.data.history;

    const updatedHistory = [
      ...history,
      { actor: "human", message: input.humanMessage },
      { actor: "agent", message: input.agentMessage }
    ];

    output.put("updatedHistory", updatedHistory);
    ```
  </Step>

  <Step title="Add Update chat session node">
    Add a **Database Operation** node to save the updated history:

    | Property                     | Value               |
    | ---------------------------- | ------------------- |
    | **Operation**                | `db.chat.updateOne` |
    | **Description**              | Update chat session |
    | **Parameter: chatSessionId** | `${chatSessionId}`  |
    | **Parameter: history**       | `${updatedHistory}` |
    | **Response Key**             | `responseKey`       |
  </Step>

  <Step title="Add Return response end node">
    Add an **End Flow** node that returns the response:

    ```json theme={"system"}
    {
      "message": {
        "chatSessionId": "${chatSessionId}",
        "agentMessage": "${agentMessage}"
      }
    }
    ```
  </Step>
</Steps>

### Chat session data model example

```json theme={"system"}
{
  "chatSessionId": "session-abc-123",
  "history": [
    {
      "actor": "human",
      "message": "Hello, I need help with my account"
    },
    {
      "actor": "agent",
      "message": "Hello! I'd be happy to help you with your account. What do you need assistance with?"
    }
  ]
}
```

***

## UI Flow integration

The Chat component integrates with UI Flows:

**Chat Component Wrapper**

* Chat component is embedded within UI Flow structure
* Follows UI template hierarchy
* Shares session context with other components

**Communication with Other Components**

<AccordionGroup>
  <Accordion title="Event-based communication" icon="broadcast-tower">
    * Components emit and listen for custom events
    * Enables loosely coupled interactions
    * Example: Chat triggers process start event
  </Accordion>

  <Accordion title="On-demand communication" icon="link">
    * Direct component-to-component calls
    * For tightly integrated features
    * Example: Chat updates task management state
  </Accordion>
</AccordionGroup>

***

## Audit and debugging

### UI Flows audit

<CardGroup>
  <Card title="Chat sessions tracking" icon="chart-line">
    All chat sessions are logged in UI Flow audit:

    * Track when chats are started
    * Monitor active and completed sessions
    * View session duration and message count
  </Card>

  <Card title="Console logging" icon="terminal">
    Access detailed execution information:

    * View workflow execution logs
    * Debug conversation flow
  </Card>
</CardGroup>

### Debug interface

**UI Flow Sessions Console**

Access comprehensive debugging tools through the **UI Flow Sessions** panel:

<Tabs>
  <Tab title="Nodes">
    Track workflow execution with node-by-node timing:

    | Node                | Typical Duration |
    | ------------------- | ---------------- |
    | Start               | 0 ms             |
    | Get chat session    | \~133 ms         |
    | Check action type   | \~52 ms          |
    | Return chat history | \~60 ms          |
  </Tab>

  <Tab title="Logs">
    View detailed execution logs:

    * Workflow Run ID and timestamps
    * Triggered from: AUTOMATIC
    * Node execution start/finish events
    * Data Source operations (FlowX Database)
    * Collection: `chat`
    * Operations: `db.chat.findOne` - Chat session history
    * Status, Time, and Size metrics
  </Tab>

  <Tab title="Input/Output">
    Inspect workflow data:

    * Input parameters passed to the workflow
    * Output data returned from nodes
    * Session state changes
  </Tab>
</Tabs>

***

## SDK integration

The Chat component is available through the FlowX SDKs for both Angular and React applications.

<CardGroup>
  <Card title="Angular SDK" icon="angular" href="../../sdks/angular-renderer#chat-component">
    Use the `FlxChatRendererComponent` in Angular applications

    ```ts theme={"system"}
    import { FlxChatRendererComponent } from '@flowx/angular-sdk';
    ```
  </Card>

  <Card title="React SDK" icon="react" href="../../sdks/react-renderer#chat-component">
    Use the `FlxChatRenderer` component in React applications

    ```tsx theme={"system"}
    import { FlxChatRenderer } from '@flowx/react-sdk';
    ```
  </Card>
</CardGroup>

### Key SDK parameters

| Parameter     | Description                                              | Required |
| ------------- | -------------------------------------------------------- | -------- |
| `apiUrl`      | Your base FlowX API URL                                  | ✅        |
| `authToken`   | Authorization token from auth provider                   | ✅        |
| `projectId`   | The FlowX project ID                                     | ✅        |
| `workspaceId` | The workspace ID                                         | ✅        |
| `source`      | Source object with workflow type and ID                  | ✅        |
| `chatConfig`  | Chat configuration object (welcome message, title, etc.) | ❌        |
| `themeId`     | Theme identifier for styling                             | ❌        |
| `language`    | Language for localization                                | ❌        |

<Info>
  For the complete list of parameters and usage examples, see the respective SDK documentation pages linked above.
</Info>

***

## Best practices

### Workflow design

<CardGroup>
  <Card title="Do" icon="circle-check">
    * Keep chat workflows focused on a single use case
    * Use clear, natural language prompts
    * Test with various user inputs
    * Handle errors gracefully with helpful messages
  </Card>

  <Card title="Don't" icon="circle-xmark">
    * Don't create overly complex conversation flows
    * Don't send responses from multiple Custom Agent nodes
  </Card>
</CardGroup>

### User experience

<CardGroup>
  <Card title="Do" icon="circle-check">
    * Provide clear initial greeting messages
    * Show typing indicators during processing
    * Display helpful error messages
    * Allow users to restart conversations
  </Card>

  <Card title="Don't" icon="circle-xmark">
    * Don't make users wait too long for responses
    * Don't use technical jargon in agent messages
    * Don't lose conversation context
  </Card>
</CardGroup>

### Performance

<CardGroup>
  <Card title="Do" icon="circle-check">
    * Optimize workflow execution time
    * Cache frequently accessed data
    * Limit message history retrieval
  </Card>

  <Card title="Don't" icon="circle-xmark">
    * Don't load entire conversation history every time
    * Don't make unnecessary API calls
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Chat not loading" icon="circle-exclamation">
    **Possible causes:**

    * Workflow is not properly configured
    * Workflow is not published
    * UI Flow has incorrect agent ID/workflow name

    **Solutions:**

    * Verify the workflow is properly configured
    * Check that the workflow is published and active
    * Ensure UI Flow has correct agent ID/workflow name
  </Accordion>

  <Accordion title="Messages not sending" icon="circle-exclamation">
    **Possible causes:**

    * Network connectivity issues
    * Workflow is in error state
    * Configuration errors

    **Solutions:**

    * Check network connectivity
    * Verify workflow is not in error state
    * Review workflow console logs for errors
  </Accordion>

  <Accordion title="Session lost on refresh" icon="circle-exclamation">
    **Possible causes:**

    * sessionId is not persisted in storage
    * Browser storage permissions issues

    **Solutions:**

    * Ensure sessionId is persisted in storage
    * Check browser storage permissions
    * Verify session management configuration
  </Accordion>
</AccordionGroup>

***

## Knowledge Base integration

The Chat component can use **Knowledge Bases** to provide contextual, grounded AI responses.

### How it works

<Steps>
  <Step title="Create Knowledge Base">
    Set up a Knowledge Base as a Data Source in Integration Designer and upload relevant content
  </Step>

  <Step title="Content processing">
    Documents are automatically split into "chunks" and indexed for semantic search
  </Step>

  <Step title="Link to Custom Agent">
    Connect the Knowledge Base to Custom Agent nodes in your workflow
  </Step>

  <Step title="Context retrieval">
    When a user sends a message, relevant chunks are retrieved based on semantic similarity
  </Step>
</Steps>

### Supported file formats

| Format         | Description                        |
| -------------- | ---------------------------------- |
| **PDF**        | Standard PDF documents             |
| **Markdown**   | `.md` files with formatted text    |
| **Word**       | Microsoft Word documents (`.docx`) |
| **Excel**      | Spreadsheet data (`.xlsx`)         |
| **PowerPoint** | Presentation files (`.pptx`)       |
| **Images**     | Image files with text content      |

### Configuration options

| Option                  | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| **Minimum relevance**   | Threshold for chunk relevance scores (0-1)                      |
| **Number of responses** | Limit how many relevant chunks are returned to the LLM          |
| **Content updates**     | Use workflows to dynamically append, update, or replace content |

<Info>
  Knowledge Bases provide **Retrieval-Augmented Generation (RAG)** capabilities, ensuring AI responses are grounded in your organization's actual data.
</Info>

<Card title="Knowledge Base Documentation" icon="book" href="../docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
  See the complete Knowledge Base documentation for setup guides and best practices.
</Card>

***

## Platform availability

<Tabs>
  <Tab title="Web">
    * All four display modes: Inline, Overlay, FullScreen, Floating
    * Complete feature set including Suggested Prompts, Markdown rendering, and voice input
    * Angular and React renderer support
  </Tab>

  <Tab title="Mobile">
    * iOS and Android support via native renderers
    * Inline, Floating, and FullScreen display modes
    * Native chat experience optimized for mobile
    * Per-platform theme configuration (padding, margin per mode)
  </Tab>
</Tabs>

***

## Related resources

<CardGroup>
  <Card title="Chat UI configuration" href="../docs/building-blocks/ui-designer/ui-component-types/chat" icon="palette">
    Settings, styling, and theme configuration
  </Card>

  <Card title="Chat interface concepts" href="./using-agents/chat-interface" icon="comments">
    High-level integration patterns
  </Card>

  <Card title="Custom Agent Node" href="../docs/platform-deep-dive/integrations/custom-agent-node" icon="robot">
    Custom Agent nodes in Integration Designer
  </Card>

  <Card title="Knowledge Base" href="../docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview" icon="database">
    Configure knowledge bases for grounded AI responses
  </Card>

  <Card title="Conversational workflows" href="./conversational-workflows" icon="messages">
    Build multi-turn chat experiences with session memory and intent routing
  </Card>
</CardGroup>


# Conversational workflows
Source: https://docs.flowx.ai/5.9/ai-platform/conversational-workflows

Build multi-turn, AI-powered chat experiences with session memory, intent routing, and context-aware responses.

## Overview

Conversational workflows are a specialized workflow type designed for multi-turn chat interactions. Unlike output focused workflows that process structured input/output, conversational workflows manage ongoing dialogue between users and AI agents — handling message exchange, session memory, and response routing.

When creating a workflow in the Integration Designer, you choose the workflow type: **Chat Driven** or **Output Focused**. This choice is permanent and cannot be changed after creation.

<Frame>
  ![Conversational workflow canvas with Start, Custom Agent, and End Flow nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_canvas.png)
</Frame>

<CardGroup>
  <Card title="Session memory" icon="brain">
    Automatically persist and retrieve conversation history across messages within a session
  </Card>

  <Card title="Dedicated Start node" icon="message">
    The Start node provides Chat Session ID, User Message, and optional UI Flow Context fields for receiving chat input
  </Card>

  <Card title="Chat replies" icon="reply">
    AI agent nodes send responses directly to the Chat component in real time
  </Card>

  <Card title="Intent routing" icon="route">
    Classify user messages and route to appropriate workflow branches using the Intent Classification node
  </Card>
</CardGroup>

***

## Chat driven vs output focused workflows

| Aspect                | Chat Driven                                               | Output Focused                     |
| --------------------- | --------------------------------------------------------- | ---------------------------------- |
| **Purpose**           | Multi-turn dialogue with users                            | Structured input/output processing |
| **Start node**        | Chat Session ID + User Message + optional UI Flow Context | Standard Start node (JSON input)   |
| **Memory**            | Built-in session memory                                   | No memory                          |
| **Response delivery** | Direct chat reply from Custom Agent nodes                 | Output on End node                 |
| **Data model**        | Input/Output tabs hidden                                  | Full data model access             |
| **Integration**       | Chat component only                                       | Process actions, subworkflows, API |

<Warning>
  The workflow type cannot be changed after creation. Choose the appropriate type when creating the workflow.
</Warning>

***

## How it works

<Steps>
  <Step title="User sends a message">
    The Chat component sends the user's message and session ID to the workflow.
  </Step>

  <Step title="Memory retrieval">
    The Start node retrieves session memory — the latest 3 message turns plus a summary of earlier conversation history.
  </Step>

  <Step title="AI processing">
    The workflow processes the message through AI nodes. Nodes with **Use Memory** enabled receive the conversation history as context for their LLM calls.
  </Step>

  <Step title="Response delivery">
    The Custom Agent node with **Send as Chat Reply** enabled sends its response directly to the Chat component in Markdown format.
  </Step>

  <Step title="Memory update">
    The system stores the user message and AI response in session memory, updating the conversation summary if needed.
  </Step>
</Steps>

***

## Start node

In Chat Driven workflows, the Start node provides dedicated input fields instead of the standard JSON editor:

| Field               | Description                                                                                                                                                                                           | Notes                                                |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Chat Session ID** | Unique session identifier. Must be a valid UUID. At runtime, the Chat component generates this automatically. For testing, enter any valid UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`).       | Required. Used for memory retrieval and storage      |
| **User Message**    | The user's message text                                                                                                                                                                               | Required. Referenced in nodes using `${userMessage}` |
| **UI Flow Context** | JSON object passed alongside the user message to provide additional context (e.g., current page, customer ID, or other UI state). Collapsed by default under an expandable section on the Start node. | Optional. Must be a valid JSON object if provided    |

At runtime, Chat Session ID and User Message are populated automatically by the Chat component, and the UI Flow Context is populated from the [Conversation Context](#setting-context-from-a-ui-flow) configured on the originating UI Flow. When testing manually via **Run Workflow**, you enter values directly in these fields on the Start node.

<Frame>
  ![Start node with Chat Session ID, User Message, and UI Flow Context fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
</Frame>

<Warning>
  The Chat Session ID **must be a valid UUID**. Using a plain string (e.g., `test-session-1`) causes a runtime error: `Invalid UUID string`.
</Warning>

<Info>
  The Start node in Chat Driven workflows is not a separate node type — it is the same Start node with a different layout tailored for chat input.
</Info>

***

## Setting context from a UI Flow

UI Flows can attach a **Conversation Context** to the Chat interaction. At runtime, the resolved JSON is delivered to the conversational workflow as the Start node's **UI Flow Context**, giving the agent access to whatever UI state the page chose to share (active record IDs, selected filters, user profile fields, etc.).

<Frame>
  ![Conversation Context property with Parameters JSON field on a UI Flow Page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context_prop_ui_flow_ui_designer.png)
</Frame>

### Configuring the property

On a Page in the UI Flow designer, open the **Settings** panel and expand **Conversation Context**. Fill in the **Parameters** field with a JSON object containing the keys the workflow should receive.

**Example:**

```json theme={"system"}
{
  "customerId": "${customerData.id}",
  "currentPage": "order-details"
}
```

<Tip>
  Use `${expression}` syntax to reference UI Flow data — values are resolved at runtime before the payload reaches the workflow.
</Tip>

***

## Custom Agent node

In Chat Driven workflows, the Custom Agent node has additional configuration options. The full layout from top to bottom:

<Frame>
  ![Custom Agent node configuration panel in a Chat Driven workflow showing Operation Prompt, Use only prompt references as context, Use Memory, Settings, and Response options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/custom_agent_node_conv.png)
</Frame>

### Operation Prompt

The system prompt for the LLM. Use `${userMessage}` to reference the user's message.

### Use only prompt references as context

When enabled, only the input values explicitly referenced with `${...}` placeholders in the **Operation Prompt** are sent to the LLM. Everything else in the node's input is dropped before the call.

* Narrows the context the agent sees, which helps it respond more precisely
* Reduces token usage on each call, improving overall performance
* Leave ON by default; turn OFF only if the agent needs to reason over data not referenced explicitly in the prompt

### Use Memory

When enabled:

* The node includes the conversation history (retrieved via session ID) in the LLM prompt
* Memory consists of the latest 3 message turns plus a summary of earlier messages
* The session ID is sent to the AI platform, which attaches the conversation context to the prompt

### Settings

* **MCP Servers** — Select MCP tools available to the agent
* **Knowledge Base** — Connect a knowledge base for RAG-powered responses

### Response

#### Send as Chat Reply

When enabled:

* The node's output is sent directly to the Chat component as a Markdown-formatted response
* The Response Schema field is hidden (the LLM is instructed to return plain text)
* A **Chat Response** tag appears on the node header
* The response triggers a memory update (stores the user message + AI reply and iterates on the conversation summary)

<Info>
  At least one Custom Agent node in the workflow must have **Send as Chat Reply** enabled. If no node sends a chat reply, the console log displays an error.
</Info>

#### Include Task for Prompt Suggestions

When enabled, the agent generates recommended follow-up prompts that are displayed in the Chat component after the main response. Use this to guide the user toward likely next questions or actions (e.g., "Show me the loan schedule", "Compare with other products").

Leave OFF unless you specifically want AI-generated suggestions shown to the user.

#### Response Key

Always visible. Defines the key where the node output is stored in the workflow data.

#### Response Schema

Only visible when **Send as Chat Reply** is OFF. Defines the expected JSON structure of the LLM response.

***

## Session memory

Chat Driven workflows use built-in session memory stored and managed by FlowX. On each message, the system retrieves the latest 3 user/agent message pairs in full, plus a summary of earlier exchanges. This memory is injected into the LLM's system prompt for nodes with **Use Memory** enabled.

<Card title="Memory Capabilities" icon="brain" href="/5.9/ai-platform/agent-builder/memory-capabilities">
  Full guide to memory structure, summarization, debugging, and storage
</Card>

<Tip>
  The summarization runs automatically when the conversation exceeds 3 turns. Only user messages and agent responses are included — internal workflow data is not part of the memory.
</Tip>

***

## Console log

The workflow console log includes additional information for Chat Driven workflows:

<Tabs>
  <Tab title="Workflow level">
    * **Input tab** — Displays User Message and Chat Session ID in JSON format (read-only)
    * **Output tab** — Displays the chat response as text (not in JSON editor for readability)
    * **Memory tab** — Shows the conversation history and summary sent to the LLM for that workflow instance
  </Tab>

  <Tab title="Custom Agent node">
    * **Output tab** — Displays the response as text
    * **Logs tab** — Hides the response schema for nodes with **Send as Chat Reply** enabled
  </Tab>
</Tabs>

***

## Constraints

<AccordionGroup>
  <Accordion title="Cannot be used as a subworkflow" icon="diagram-project">
    Chat Driven workflows cannot be referenced as subworkflows. The subworkflow node filters out Chat Driven workflows from the selection list.
  </Accordion>

  <Accordion title="Cannot be started from Process Actions" icon="ban">
    The **Start Integration Workflow** action in processes filters out Chat Driven workflows. They can only be started through the Chat component.
  </Accordion>

  <Accordion title="User message is mandatory" icon="message">
    Running a Chat Driven workflow without a user message triggers an error: *"The user message is mandatory in conversational workflows."*
  </Accordion>

  <Accordion title="End node is required" icon="circle-check">
    A Chat Driven workflow requires an End Flow node to complete the execution path. The End Flow node is simplified (header only, no body configuration) since responses are sent from Custom Agent nodes. The End Flow node is **not auto-created** — you must add it manually from the node palette.
  </Accordion>

  <Accordion title="Chat component integration only" icon="comments">
    Only Chat Driven workflows can be integrated into the Chat component. Output Focused workflows are filtered out from the Chat component workflow selection.
  </Accordion>
</AccordionGroup>

***

## Navigate in UI Flow node

The **Navigate in UI Flow** node is an action node exclusive to Chat Driven workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — allowing the AI conversation to open forms, dashboards, or any UI flow destination with contextual data.

<Frame>
  ![Navigate in UI Flow node configuration with UI Flow, Destination, and Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
</Frame>

<Info>
  This node only appears in the **Actions** category when editing a Chat Driven workflow. It is not available in Output Focused workflows.
</Info>

### Configuration

<ParamField type="select">
  Select the UI Flow resource to navigate to. Only UI Flows in the current project and its dependencies are available.
</ParamField>

<ParamField type="select">
  The specific screen (root view) within the selected UI Flow. The destination list is fetched dynamically and displays the navigation tree of the UI Flow.

  Changing the destination resets all configured parameters.
</ParamField>

<ParamField type="key-value[]">
  Dynamic parameters passed to the destination screen as query parameters. The available parameters are defined by the destination's query parameter configuration.

  * Use `${expression}` syntax to map workflow data to parameters
  * Required parameters are marked with an asterisk (\*)
  * Default values are shown when configured on the destination

  **Example:** `${customerData.accountId}` maps the workflow's `customerData.accountId` to the destination's query parameter.
</ParamField>

### How it works

When the node executes:

1. Validates that the workflow is Chat Driven (fails with error otherwise)
2. Resolves `${expression}` placeholders in parameter values using the current workflow context
3. Sends a navigation command to the Chat component via the events gateway
4. The Chat component opens the target UI Flow screen with the resolved parameters

<Warning>
  If any required parameter resolves to an empty value after placeholder resolution, the node fails with an error. Verify that the referenced workflow data keys contain values at runtime.
</Warning>

***

## AI Triggers

AI Triggers are named message templates that allow different UI Flow pages to launch the same conversational workflow with different starting contexts. Instead of passing a plain text user message, a trigger sends a structured message with parameters that get resolved at runtime.

This is useful when multiple pages in your app need to start a conversation with the same workflow but with different initial context — for example, a "Help with this order" button on an order details page vs. a "General support" entry point.

### Key concepts

<CardGroup>
  <Card title="Named templates" icon="tag">
    Each trigger has a name, a message template with `${paramName}` placeholders, and optional parameters with default values
  </Card>

  <Card title="Parameterized context" icon="sliders">
    Parameters are resolved at runtime — different pages can pass different values for the same trigger
  </Card>

  <Card title="Transparent to the agent" icon="robot">
    The resolved message is sent as standard user input — the agent processes it like any other message
  </Card>

  <Card title="Memory integration" icon="brain">
    The trigger message is saved to conversation memory but not displayed in the user's chat history
  </Card>
</CardGroup>

### Defining triggers

<Frame>
  ![AI Trigger reply in a chat conversation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/reply_trigger.png)
</Frame>

Triggers are defined in the **AI Triggers** side nav tab (lightning icon) on a conversational workflow.

<Frame>
  ![Reply Triggers configuration panel with trigger name, user message, and parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/reply_triggers.png)
</Frame>

<Steps>
  <Step title="Open the AI Triggers tab">
    In the workflow editor, click the lightning icon in the secondary side nav. This tab only appears for Chat Driven workflows.
  </Step>

  <Step title="Add a trigger">
    Click **Add Trigger**. A form appears with the following fields:

    <ParamField type="string">
      A descriptive name for the trigger (e.g., "Order Support", "Product Question").
    </ParamField>

    <ParamField type="string">
      The message template sent as user input when the trigger fires. Supports `${paramName}` interpolation. Maximum 2000 characters.

      **Example:** `The customer needs help with order ${orderId}. Their account type is ${accountType}.`
    </ParamField>

    <ParamField type="array">
      Optional list of parameters referenced in the message template. Each parameter has:

      * **Name** (required) — the key used in `${paramName}` placeholders
      * **Default value** (optional) — used when no value is provided at runtime
      * **Description** (optional) — explains the parameter's purpose
    </ParamField>
  </Step>

  <Step title="Save the trigger">
    Click **Save** to persist the trigger. It becomes available for selection on the Start node and in UI Flow integrations.
  </Step>
</Steps>

<Tip>
  Parameters referenced in the message with `${paramName}` should match the parameter names defined in the params table. If a parameter value is left empty at runtime, the `${paramName}` placeholder is sent as-is — the workflow handles missing context.
</Tip>

### Using triggers on the Start node

The Start node of a conversational workflow provides a segmented toggle to switch between **Text** mode (default) and **AI Triggers** mode:

<Tabs>
  <Tab title="Text mode">
    The default behavior — a free-text **User Message** field, **Chat Session ID**, and an optional **UI Flow Context** JSON editor.
  </Tab>

  <Tab title="AI Triggers mode">
    * A dropdown lists all triggers defined on the workflow
    * Selecting a trigger shows:
      * A read-only preview of the message template
      * A code editor pre-filled with the trigger's parameters and their default values
    * **Chat Session ID** remains visible and required

    When no triggers are defined, an empty state is shown with a **Configure triggers** button that opens the AI Triggers tab.
  </Tab>
</Tabs>

### Chat integration

When the workflow is connected to a Chat component via a UI Flow, triggers are sent from the UI to the workflow:

* The available triggers (ID, name, and parameters) are exposed to the UI Flow
* The UI can invoke a trigger by sending the trigger ID along with parameter values
* The resolved message (with all `${paramName}` values substituted) is sent as the workflow's starting input
* The trigger message is **saved to conversation memory** for context continuity
* The trigger message is **not displayed** in the user's chat history

<Info>
  If a trigger is deleted from the workflow while still referenced by a UI Flow page, it is automatically removed from the page — the same behavior as when a REST API endpoint is removed from a system.
</Info>

### Console and run logs

Workflow runs initiated via an AI Trigger show additional details in the run history:

| Field                 | Description                                                        |
| --------------------- | ------------------------------------------------------------------ |
| **User message type** | `text` or `AI trigger`                                             |
| **Trigger**           | The trigger name (e.g., "Triggered by: Order Support")             |
| **User message**      | The fully resolved message with all `${paramName}` values replaced |

The Start node's output tab displays the full resolved input as JSON, including `user_message_type`, `trigger`, and `user_message` fields.

***

## Testing conversational workflows

When testing via **Run Workflow**, the test modal provides two modes:

### Text mode

* **Chat Session ID** — A valid UUID that identifies the test conversation session (e.g., `550e8400-e29b-41d4-a716-446655440000`). Required. Used for memory storage and retrieval.
* **User Message** — The test message to send (e.g., "What is my account balance?")
* **UI Flow Context** — Optional JSON object to mock the context a UI Flow would normally supply at runtime (e.g., `{"customerId": "42"}`). Invalid JSON is rejected before the run starts.

### AI Triggers mode

* **Chat Session ID** — Same as above, required
* **Trigger** — Select from the workflow's defined triggers
* **Parameters** — Fill in test values for the trigger's parameters (e.g., `${orderId}` → `ORD-12345`)

Clicking **Run Workflow** with an AI Trigger selected substitutes the parameter values into the message template and sends the resolved message as the workflow's starting input.

<Tip>
  When testing, use the same Chat Session ID across multiple Run Workflow executions to test multi-turn memory — the system retrieves previous messages from that session.
</Tip>

<Frame>
  ![Run Workflow test modal with Chat Session ID and User Message fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_test_modal.png)
</Frame>

***

## Setting up a conversational workflow

<Steps>
  <Step title="Create a new workflow">
    In the Integration Designer, click **+** to create a new workflow. Enter a name and select **Chat Driven** as the workflow type.

    <Frame>
      ![Create workflow modal with Chat Driven selected as the workflow type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/mainChat_chat_driven_create.png)
    </Frame>
  </Step>

  <Step title="Review the Start node">
    The Start node is created automatically with **Chat Session ID**, **User Message**, and an optional **UI Flow Context** editor pre-configured.
  </Step>

  <Step title="Add AI processing nodes">
    Add Custom Agent nodes or [Intent Classification](/5.9/ai-platform/agent-builder/intent-classification) nodes to process user messages.
  </Step>

  <Step title="Enable Chat Reply">
    On the Custom Agent node that generates the final response, toggle **Send as Chat Reply** to **ON**.
  </Step>

  <Step title="Enable Memory (optional)">
    On nodes that need conversation context, toggle **Use Memory** to **ON**.
  </Step>

  <Step title="Add an End Flow node">
    Add an End Flow node from the node palette and connect it to the final node in your workflow. The End Flow node has no body configuration in Chat Driven workflows.
  </Step>

  <Step title="Integrate with a UI Flow">
    Connect the conversational workflow to your UI:

    * **Option A (5.7.0+):** Create a **Chat-Based UI Flow** and select this workflow as the default conversational workflow. All Chat components in the UI Flow will use it automatically.
    * **Option B:** In any UI Flow, add a Chat component and select the Chat Driven workflow directly on the component.

    <Frame>
      ![Create UI Flow modal with Chat-Based selected as the experience type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_chat_based.png)
    </Frame>

    <Frame>
      ![Chat-Based UI Flow hosting a conversational workflow in a Chat component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_ui_flow.png)
    </Frame>
  </Step>
</Steps>

***

## Cancelling a running workflow

### Endpoint

```bash theme={"system"}
POST /api/runtime/wks/{workspaceId}/app/{appId}/workflows/instances/{instanceUuid}/cancel
```

**Path parameters:**

| Parameter      | Type   | Description                     |
| -------------- | ------ | ------------------------------- |
| `workspaceId`  | UUID   | The workspace identifier        |
| `appId`        | UUID   | The app identifier              |
| `instanceUuid` | string | The workflow instance to cancel |

The caller must have access to the target workspace within their organization.

### Cancellation behavior

What happens depends on where the workflow instance is when the cancel request arrives:

* **Before any AI node runs** — The user prompt is persisted on the chat message with `cancelled: true`. No AI call is made. The workflow stops.
* **While an AI node is executing** — The in-flight AI call is stopped, any partial response is discarded, and the user prompt is persisted with `cancelled: true`. The workflow stops.

In both cases, the Chat component receives a `chatCancelled` Server-Sent Event on the `CHAT_WORKFLOW_RESPONSE` channel so the UI can exit its streaming state.

***

## Related resources

<CardGroup>
  <Card title="Chat component" icon="comments" href="/5.9/ai-platform/chat-component">
    Technical reference for runtime behavior, session management, and SDK integration
  </Card>

  <Card title="AI node types" icon="diagram-project" href="/5.9/ai-platform/agent-builder/node-types">
    Overview of all available AI workflow node types
  </Card>

  <Card title="Chat interface" icon="message" href="/5.9/ai-platform/using-agents/chat-interface">
    Conceptual overview of adding conversational AI to your apps
  </Card>

  <Card title="Knowledge Base" icon="book" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
    Connect knowledge bases for context-aware AI responses
  </Card>
</CardGroup>


# Evaluations
Source: https://docs.flowx.ai/5.9/ai-platform/evaluations

Score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Catalogue, datasets, experiments, and the evals-judge service.

<Info>
  Attach test cases to AI nodes in a workflow, pick from a catalogue of evaluators (correctness, hallucination, RAG groundedness, JSON match, and more), launch an experiment, and read per-evaluator aggregate scores plus per-test-case details. Powered by the async `evals-judge` service.
</Info>

## Overview

An *evaluation* (eval) scores the output of an AI node against a known expected outcome. Use evals to:

* **Tune prompts and retrieval** — change a system prompt or KB chunk size, rerun the same experiment, and see whether your scores improved.
* **Regression-guard agents** — before promoting a new agent version, run the dataset of "hard" past inputs and compare scores against the previous version.
* **Pick a model** — run the same dataset against two different LLMs and compare correctness, conciseness, and cost.

Evals are workflow-centric in 5.9.0. Each dataset is attached to a specific AI node in a specific workflow; experiments launch that workflow against the dataset and score the node's outputs.

***

## Core concepts

| Concept                | What it is                                                                                                                                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dataset**            | A named collection of test cases attached to a specific AI node in a workflow. Holds the node configuration snapshot at the time the dataset was last updated.               |
| **Test case**          | One row of input data plus an expected output. May include retrieved context. Sourced either **manually** or captured from a real **node execution** in a workflow run.      |
| **Evaluator (scorer)** | A pre-seeded rule that scores a model output against the expected output. Belongs to one of three categories — LLM-as-judge, RAG-quality, or code-exact-match.               |
| **Experiment**         | A run of the workflow against every test case in one or more datasets, scored by one or more evaluators. Produces aggregate scores per evaluator plus per-test-case details. |
| **Score**              | Numeric (typically 0.0–1.0) or binary, depending on the evaluator. Numeric scorers have a default pass/fail threshold.                                                       |

***

## Get started

<Steps>
  <Step title="Add an AI node to a workflow">
    Drop a Custom Agent, Intent Classification, Extract Data, or any other AI node into a workflow and configure it as usual.
  </Step>

  <Step title="Create a dataset on the node">
    From the node's side panel, open **Evaluations → Datasets** and click **New dataset**. Name it after what it tests (e.g. *Customer-intent-classification-baseline*).
  </Step>

  <Step title="Add test cases">
    Add at least one test case manually, or capture one from an existing process instance run (see [Add test cases](#add-test-cases)).
  </Step>

  <Step title="Pick evaluators">
    Open **Evaluations → Experiments → New experiment**. Choose one or more datasets and pick the evaluators you want to score against from the catalogue.
  </Step>

  <Step title="Launch the experiment">
    Click **Start**. The workflow runs against every test case; the `evals-judge` service scores each (test case × evaluator) pair asynchronously.
  </Step>

  <Step title="Read the results">
    Once the experiment moves to `PASSED` or `FAILED`, open the report for aggregate scores per evaluator and a list of test-case rows you can drill into.
  </Step>
</Steps>

***

## Create a dataset

A dataset belongs to a single AI node on a single workflow. Two datasets on the same node must have unique names.

Fields:

| Field                     | Description                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| **Name**                  | Human-readable label, unique per node.                                                       |
| **Description**           | Optional. Useful for explaining "what is this dataset testing?"                              |
| **Multimodal**            | Toggle on if test cases include image or file inputs as well as text.                        |
| **Output shape contract** | Optional JSON schema describing the expected output shape. Used by the JSON Match evaluator. |

The dataset persists a *schema snapshot* of the node's input/output at the time of last edit. This is what's used when a workflow is changed underneath an existing dataset — the experiment runs against the snapshot, not the live node, so older runs remain reproducible.

***

## Add test cases

A test case has three core fields:

* **Input** — the data the AI node receives.
* **Expected output** — what a correct response looks like. Required by exact-match and JSON-match evaluators; optional but recommended for LLM-as-judge.
* **Context** — optional retrieved context (KB chunks, retrieval results) used to score RAG evaluators.

Two ways to add them:

<Tabs>
  <Tab title="Manual">
    From the dataset's **Test cases** tab, click **Add test case**. Fill in **Input**, **Expected output**, and optional **Context**. Save.

    Use this for synthetic or hand-crafted cases — typical edge cases, known-difficult inputs, or cases borrowed from a spec or QA tracker.
  </Tab>

  <Tab title="From a node execution">
    Open a real process instance in the runtime, find the AI node execution you want to capture, and choose **Add to dataset**. FlowX serialises the node's input, captured output, and any retrieved context into a new test case on the chosen dataset.

    Use this to harvest "interesting" production cases (high-uncertainty completions, ones flagged by an operator) into a regression set.

    Captured cases are marked with `source: NODE_EXECUTION` and carry a back-reference to the originating execution.
  </Tab>
</Tabs>

***

## Launch an experiment

An experiment binds together:

* One or more datasets (all must be on the same AI node)
* One or more evaluators
* A node configuration snapshot (frozen at launch time)

When you click **Start**, the workflow runs end-to-end against every test case. Each output produces one judge job per (test case × evaluator), published to the `evals-judge.job.request` Kafka topic. `evals-judge` resolves the configured judge LLM, runs the scoring prompt, and returns a score + reasoning on `evals-judge.job.response`.

Experiment status moves through:

| Status      | Meaning                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `STARTED`   | Experiment accepted, workflows are being scheduled.                                                         |
| `RUNNING`   | At least one (test case × evaluator) pair is still scoring.                                                 |
| `PASSED`    | All scoring jobs completed; overall score is above the pass threshold for the experiment.                   |
| `FAILED`    | All scoring jobs completed; overall score is below threshold (or a non-trivial number of jobs hit the DLQ). |
| `CANCELLED` | Cancelled by a user before completion.                                                                      |

The Designer streams progress updates as scoring jobs complete, so the report fills in live without a full reload.

***

## View results

Each experiment produces a **report** with two views:

### Aggregate scores

A row per evaluator with the mean (or pass-rate) across all test cases. Useful for "is this prompt better than the last one?" comparisons.

### Per-test-case details

A row per test case showing:

* The input, the model's actual output, and the expected output side-by-side.
* One score column per evaluator selected for the experiment.
* For LLM-as-judge evaluators, the judge's reasoning text (the model's own explanation of the score).
* Pass/fail badges against each evaluator's threshold.

Click into a row to see the full prompt, response, and any retrieved context — this is the screen you use to debug "why is this case failing?"

***

## Evaluator catalogue

5.9.0 ships **10 built-in evaluators** in three categories. The catalogue is read-only — user-defined evaluators are planned for a later release.

### LLM-as-judge

A judge LLM reads the model output (and optional expected output) and scores it on a single rubric. Score is numeric 0.0–1.0.

| Evaluator            | What it scores                                                                    | Needs expected output? |
| -------------------- | --------------------------------------------------------------------------------- | ---------------------- |
| **Correctness**      | How closely the output matches the expected meaning.                              | Yes                    |
| **Conciseness**      | Whether the output is appropriately brief — penalises padding and rambling.       | No                     |
| **Hallucination**    | Whether the output contains claims not grounded in the input or provided context. | No                     |
| **Answer relevance** | Whether the output actually answers what the input asked.                         | No                     |

### RAG quality

Evaluators that judge the *retrieval* side of a RAG workflow. Score is numeric 0.0–1.0.

| Evaluator               | What it scores                                                                    |
| ----------------------- | --------------------------------------------------------------------------------- |
| **Groundedness**        | Is every claim in the output supported by the retrieved context?                  |
| **Helpfulness**         | Does the retrieved context actually help answer the question, or is it off-topic? |
| **Retrieval relevance** | Are the top retrieved chunks the most relevant to the question?                   |

### Code

Deterministic, no LLM call. Useful for structured outputs.

| Evaluator       | What it scores                                                            | Score type |
| --------------- | ------------------------------------------------------------------------- | ---------- |
| **Exact match** | Output equals expected, character-for-character.                          | Binary     |
| **Levenshtein** | Edit-distance similarity between output and expected (normalised).        | Numeric    |
| **JSON match**  | Output is valid JSON and conforms to the dataset's output-shape contract. | Binary     |

### Score types and thresholds

* **Numeric evaluators** return a score in `[0.0, 1.0]` and ship with a `defaultThreshold` (e.g. `0.7`). The report flags a row as failing if the score is below the threshold.
* **Binary evaluators** return pass or fail. No threshold.

***

## Judge model resolution

LLM-as-judge and RAG evaluators need a judge LLM to run their scoring prompts. The model is resolved **per organization** via a new LLM capability:

* 5.9.0 adds the **`EVAL`** capability to the org-manager LLM catalogue (display order 7, alongside the existing capabilities).
* The platform-default judge model is **`gpt-5.4-mini`**, backfilled onto every org's catalogue on upgrade.
* An admin can change the judge model per org by assigning `EVAL` to a different model in **Settings → AI Providers → Models**.

This means the same experiment can produce slightly different scores in two different orgs if they've picked different judge models — the report records which model was used, so the comparison stays apples-to-apples within one org.

<Info>
  The judge LLM is *not* the same as the LLM your agent uses. The agent under test can use any provider; the judge runs separately and can be a cheaper, faster model dedicated to scoring.
</Info>

***

## Permissions

Evals reuse existing workflow-level permissions — there is no new role.

| Capability                                                                                       | Permission      |
| ------------------------------------------------------------------------------------------------ | --------------- |
| List, view datasets, experiments, reports                                                        | `WORKFLOW_READ` |
| Create / update / delete datasets, add / remove test cases, launch / cancel / delete experiments | `WORKFLOW_EDIT` |

Permissions are enforced per workflow resource ID — a user with `WORKFLOW_EDIT` on Workflow A but not Workflow B cannot launch an experiment against B's nodes.

***

## How it works

The runtime side has three pieces:

* **`integration-designer`** owns the dataset, test-case, and experiment REST APIs and the experiment orchestration. It publishes judge job requests to Kafka and writes results to MongoDB.
* **`evals-judge`** is a small Python service that consumes judge job requests, resolves the judge LLM via `organization-manager`, calls the LLM provider, and publishes scored responses.
* **`organization-manager`** owns the LLM catalogue and resolves the model bound to the `EVAL` capability for the org.

Scoring is fully async. A judge job's lifecycle:

1. `integration-designer` publishes a request on `ai.flowx.ai-platform.evals-judge.job.request.v1` with the test case, the evaluator id, and the node-config snapshot.
2. `evals-judge` consumes the request, resolves the judge model, runs the scoring prompt, and publishes the result on `ai.flowx.ai-platform.evals-judge.job.response.v1`.
3. `integration-designer` consumes the response, persists the score on the test-case row, and pushes a progress event over SSE to any open Designer report.
4. Permanent failures (no judge model resolvable, invalid request shape, repeated timeouts) end up on `ai.flowx.ai-platform.evals-judge.job.dlq.v1` for manual operator review — the report shows the test-case row as `ERROR`.

***

## REST API surface

The Designer is the primary entry point, but the same endpoints are usable from your own tooling. All are scoped to a workspace and require `WORKFLOW_READ` / `WORKFLOW_EDIT` on the relevant workflow.

| Method             | Endpoint                                                                | Purpose                                             |
| ------------------ | ----------------------------------------------------------------------- | --------------------------------------------------- |
| POST               | `/api/workflows/datasets`                                               | Create a dataset on a node                          |
| GET                | `/api/workflows/datasets?nodeFlowxUuid={uuid}`                          | List datasets, optionally filtered to one node      |
| GET / PUT / DELETE | `/api/workflows/datasets/{datasetUuid}`                                 | Fetch, update name/description, or delete a dataset |
| POST               | `/api/workflows/datasets/{datasetUuid}/test-cases`                      | Add a test case (manual)                            |
| POST               | `/api/workflows/experiments/start`                                      | Launch an experiment                                |
| GET                | `/api/workflows/experiments`                                            | List experiments (paginated)                        |
| GET                | `/api/workflows/experiments/{experimentUuid}`                           | Experiment report with aggregate scores             |
| GET                | `/api/workflows/experiments/{experimentUuid}/test-cases/{testCaseUuid}` | One test-case row with all scores                   |
| POST               | `/api/workflows/experiments/{experimentUuid}/cancel`                    | Cancel a running experiment                         |
| DELETE             | `/api/workflows/experiments/{experimentUuid}`                           | Delete a completed or cancelled experiment          |

***

## Operator setup

Evals add a new service and three new Kafka topics to the AI Platform deployment.

### evals-judge service

* **Language:** Python
* **Container image:** `{{flowx-ai}}/evals-judge`
* **Dependencies:** Kafka (request / response / DLQ), `organization-manager` (LLM resolution), the LLM provider configured for the `EVAL` capability, S3-compatible storage (MinIO env vars on multimodal test cases).
* **No exposed ingress.** Communication is Kafka-only.
* **Storage:** none of its own — state lives in `integration-designer`'s MongoDB and the LLM provider.

Add `evals-judge` to your AI Platform install. See [AI Platform setup](/5.9/ai-platform/ai-platform-setup#service-architecture) for the full Python services list.

### Kafka topics

Declare the following in your Kafka provisioning (`kafka-topics.yaml.gotmpl` for k8s, or your own topic management):

| Topic                                              | Partitions | Purpose                                         |
| -------------------------------------------------- | ---------- | ----------------------------------------------- |
| `ai.flowx.ai-platform.evals-judge.job.request.v1`  | 3          | Judge job requests from `integration-designer`  |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | 3          | Scored responses back to `integration-designer` |
| `ai.flowx.ai-platform.evals-judge.job.dlq.v1`      | 3          | Dead-letter queue for unscored jobs             |

The `integration-designer` consumer group for the response topic is `integration-designer-evals-judge-response-group` with 3 consumer threads by default.

### EVAL capability backfill

The migration `20260513_eval_capability.xml` runs on the first `organization-manager` boot after upgrade and:

* Registers the `EVAL` capability in `llm_capability_catalog` (display order 7).
* Backfills `gpt-5.4-mini` as the model bound to `EVAL` in `llm_model_catalog` (platform default).
* Backfills the same binding into every existing organization's `llm_model` table so evals work out-of-the-box on upgrade without manual configuration.

If your org uses a non-OpenAI provider, change the bound model in **Settings → AI Providers → Models** after the upgrade.

***

## Limitations in 5.9.0

* **No user-defined evaluators.** The 10-evaluator catalogue is read-only. Custom rubrics and custom scoring prompts are planned for a later release.
* **No eval suggestions.** The `EVAL_SUGGESTIONS` capability is registered but reserved — there is no producer in 5.9.0.
* **Workflow-scoped only.** Datasets bind to a single AI node on a single workflow. Cross-workflow shared datasets are out of scope.
* **Judge model is org-wide.** Picking a different judge per evaluator or per experiment is not supported.
* **No retroactive backfill across workflow rewrites.** If you change the AI node's contract significantly, existing datasets keep their snapshot — they don't fail, but they may no longer reflect the current workflow's behaviour. Create a new dataset.
* **DLQ is manual.** There is no automatic retry for jobs landing on the DLQ; an operator must inspect and decide whether to retry.

***

## Related resources

<CardGroup>
  <Card title="AI Platform setup" icon="server" href="./ai-platform-setup">
    Install evals-judge alongside the rest of the AI Platform.
  </Card>

  <Card title="AI providers" icon="plug" href="./ai-providers">
    Configure the LLM bound to the `EVAL` capability for your org.
  </Card>

  <Card title="Agent Builder overview" icon="robot" href="./agent-builder/overview">
    Build the AI agents whose outputs you'll score.
  </Card>

  <Card title="Conversational workflows" icon="diagram-project" href="./conversational-workflows">
    Conversational workflow nodes you can attach datasets to.
  </Card>
</CardGroup>


# AI integrations
Source: https://docs.flowx.ai/5.9/ai-platform/integrations

Connect AI agents to external data sources, APIs, and knowledge bases.

AI agents can connect to external systems and data sources to provide context-aware, informed responses. This page provides an overview of available integration options.

## Data source integrations

<CardGroup>
  <Card title="Knowledge bases" icon="database" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
    Connect document repositories for RAG-powered responses
  </Card>

  <Card title="MCP integration" icon="link" href="/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview">
    Use Model Context Protocol to connect external tools and data
  </Card>
</CardGroup>

## Workflow integrations

<CardGroup>
  <Card title="Integration Designer" icon="diagram-project" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Build complex integration workflows with visual designer
  </Card>

  <Card title="Custom Agent Node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
    Use AI agents within Integration Designer workflows
  </Card>
</CardGroup>

## API access

<CardGroup>
  <Card title="REST APIs" icon="code" href="/5.9/docs/api/process-api">
    Programmatic access to processes and agents
  </Card>

  <Card title="Kafka integration" icon="bolt" href="/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka">
    Event-driven integration patterns
  </Card>
</CardGroup>

## Integration patterns

| Pattern                    | Description                                     | Use case                             |
| -------------------------- | ----------------------------------------------- | ------------------------------------ |
| **Knowledge retrieval**    | Agent queries knowledge bases before responding | Context-aware chat, document Q\&A    |
| **External API calls**     | Agent calls external services via MCP           | Real-time data, third-party services |
| **Workflow orchestration** | Agent triggers or is triggered by workflows     | Automated processing pipelines       |
| **Event-driven**           | Agent responds to Kafka events                  | Real-time processing, notifications  |

## Related resources

<CardGroup>
  <Card title="Agent Builder" icon="robot" href="./agent-builder/overview">
    Create custom AI agents
  </Card>

  <Card title="Using agents" icon="play" href="./using-agents/overview">
    Integration patterns for agents
  </Card>
</CardGroup>


# AI comparison and reconciliation
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/ai-comparison-reconciliation

Compare AI-extracted document data against system-of-record values and generate structured exception reports with match rates and confidence scores.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

The AI comparison and reconciliation pattern uses TEXT\_UNDERSTANDING nodes as comparison agents to perform field-by-field validation between AI-extracted data and expected values from a system of record. The output is a structured exception report that drives downstream routing: auto-approve, human review, or reject.

***

## When to use

Use this pattern when you need to:

* Validate AI-extracted document data against a trusted source (TMS, ERP, core banking system, database)
* Produce auditable, structured comparison results with per-field match status
* Route exceptions based on severity and overall match rate
* Replace manual spot-checking of document extraction results

This pattern typically follows the [fan-out extraction](./fan-out-extraction) pattern in a document processing pipeline.

***

## Architecture

The workflow accepts two data sets as input, runs them through a TEXT\_UNDERSTANDING comparison agent, and routes the result based on the exception report.

```
Extracted Data + System Data
        |
        v
 TEXT_UNDERSTANDING (compare)
        |
        v
   Exception Report
        |
        v
   Condition (severity routing)
      /       |       \
     v        v        v
Auto-approve  Human   Reject
              review
```

**Node breakdown:**

| Node             | Type                | Purpose                                                    |
| ---------------- | ------------------- | ---------------------------------------------------------- |
| **Compare**      | TEXT\_UNDERSTANDING | Field-by-field comparison of extracted vs. expected values |
| **Route**        | Condition           | Branch based on overall match rate and exception severity  |
| **Auto-approve** | End / next step     | High-match documents proceed without intervention          |
| **Human review** | End / next step     | Medium-match documents queued for manual review            |
| **Reject**       | End / next step     | Low-match documents flagged for rejection                  |

***

## Implementation

### Input structure

The comparison node receives two objects: the AI-extracted values and the system-of-record values.

```json theme={"system"}
{
  "extractedData": {
    "shipperName": "Acme Logistics Ltd.",
    "consigneeName": "Beta Corp",
    "totalWeight": "14500",
    "weightUnit": "KG",
    "containerCount": 3,
    "bolNumber": "MSKU-2024-78432"
  },
  "systemData": {
    "shipperName": "Acme Logistics",
    "consigneeName": "Beta Corporation",
    "totalWeight": "14500",
    "weightUnit": "KG",
    "containerCount": 3,
    "bolNumber": "MSKU-2024-78432"
  }
}
```

### Comparison prompt

Configure the TEXT\_UNDERSTANDING node with a prompt that instructs the LLM to perform structured comparison.

```text theme={"system"}
You are a document reconciliation agent. Compare the AI-extracted values against
the system-of-record values and produce a structured exception report.

Instructions:
1. Compare each field individually. Use fuzzy matching for names and addresses
   (e.g., "Acme Logistics Ltd." vs "Acme Logistics" is a MATCH).
2. For numeric fields, compare exact values. Flag unit mismatches separately.
3. For derived values (e.g., total weight = sum of line items), verify the
   calculation independently.
4. Compute an overall match rate as a percentage (0-100).
5. Assign a confidence score (0-100) reflecting how certain you are in the
   comparison results.
6. Flag each exception with a severity: CRITICAL, WARNING, or INFO.

Extracted data:
{{extractedData}}

System-of-record data:
{{systemData}}
```

### Output schema

Define the output schema on the TEXT\_UNDERSTANDING node to enforce structured results.

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "matchRate": {
      "type": "number",
      "description": "Overall match rate from 0 to 100"
    },
    "confidenceScore": {
      "type": "number",
      "description": "Confidence in comparison accuracy from 0 to 100"
    },
    "fieldResults": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": { "type": "string" },
          "extractedValue": { "type": "string" },
          "expectedValue": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["MATCH", "MISMATCH", "MISSING"]
          },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "WARNING", "INFO"]
          },
          "note": { "type": "string" }
        },
        "required": ["fieldName", "status"]
      }
    },
    "exceptions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": { "type": "string" },
          "description": { "type": "string" },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "WARNING", "INFO"]
          }
        },
        "required": ["fieldName", "description", "severity"]
      }
    }
  },
  "required": ["matchRate", "confidenceScore", "fieldResults", "exceptions"]
}
```

### Severity routing

Configure a Condition node after the comparison to route based on the exception report.

| Route            | Condition                                                         | Action                          |
| ---------------- | ----------------------------------------------------------------- | ------------------------------- |
| **Auto-approve** | `matchRate >= 95` and no CRITICAL exceptions                      | Proceed to next processing step |
| **Human review** | `matchRate >= 70` and `matchRate < 95`, or any WARNING exceptions | Queue for manual review         |
| **Reject**       | `matchRate < 70` or any CRITICAL exception                        | Flag for rejection and notify   |

<Tip>
  Adjust the match rate thresholds based on your business requirements. Start conservative (higher thresholds for auto-approve) and relax them as you gain confidence in extraction quality.
</Tip>

***

## Configuration reference

| Setting           | Value               | Description                                         |
| ----------------- | ------------------- | --------------------------------------------------- |
| **Node type**     | TEXT\_UNDERSTANDING | Comparison agent                                    |
| **Temperature**   | `0`                 | Use deterministic output for consistent comparisons |
| **Output format** | JSON schema         | Structured exception report                         |
| **Max tokens**    | `2000`              | Sufficient for detailed field-by-field reports      |

***

## Exception severity levels

| Severity     | Description                                 | Examples                                                                                       |
| ------------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **CRITICAL** | Data integrity issue that blocks processing | Missing required field, numeric value off by more than 10%, wrong document matched to shipment |
| **WARNING**  | Discrepancy that requires human judgment    | Name variation beyond fuzzy match threshold, date format ambiguity, unit conversion needed     |
| **INFO**     | Minor difference, typically acceptable      | Abbreviation vs. full name, trailing whitespace, formatting differences                        |

***

## Variations

### Threshold-based routing

Instead of fixed severity categories, use configurable thresholds stored in a FlowX Database data source. This allows business users to adjust auto-approve and reject boundaries without modifying the workflow.

### Multi-document cross-reference

Extend the pattern to compare fields across multiple documents in the same shipment. For example, verify that the total weight on the bill of lading matches the sum of weights on the packing list and that both align with the commercial invoice.

### Audit trail generation

Add a downstream node that persists the full exception report (including all MATCH results) to a database or document store. This provides a complete audit trail for compliance and quality monitoring over time.

***

## Related resources

<CardGroup>
  <Card title="AI patterns overview" icon="puzzle-piece" href="./overview">
    All available AI patterns and how to combine them
  </Card>

  <Card title="Fan-out extraction" icon="arrows-split-up-and-left" href="./fan-out-extraction">
    Classify and extract from multiple document types
  </Card>

  <Card title="Hybrid AI + business rules" icon="scale-balanced" href="./hybrid-ai-rules">
    Combine AI with deterministic logic for auditable decisions
  </Card>

  <Card title="AI node types" icon="diagram-project" href="../agent-builder/node-types">
    Reference for all AI node types including TEXT\_UNDERSTANDING
  </Card>
</CardGroup>


# Fan-out extraction
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/fan-out-extraction

Classify documents by type, then route each to a specialized extraction node with tailored prompts and schemas. Scale to dozens of document types.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

## When to use

Use fan-out extraction when your app needs to process documents that vary significantly in structure and content. A single extraction prompt cannot handle the differences between an invoice, a bill of lading, and a fuel receipt — each has different fields, layouts, and validation rules.

This pattern is the right choice when:

* You receive **mixed document types** in a single pipeline (email attachments, bulk uploads)
* Each document type has a **distinct schema** with specialized fields
* You need **high extraction accuracy** per type rather than a generic best-effort pass
* The number of document types may **grow over time** without rearchitecting the workflow

***

## Architecture

The pattern follows two phases: classification, then type-specific extraction.

```text theme={"system"}
Document
  │
  ▼
TEXT_UNDERSTANDING (classify type)
  │
  ▼
Condition (fork by type)
  ├──► TEXT_EXTRACTION (Type A) ──►─┐
  ├──► TEXT_EXTRACTION (Type B) ──►─┤
  ├──► TEXT_EXTRACTION (Type C) ──►─┤
  └──► TEXT_EXTRACTION (Type N) ──►─┘
                                    │
                                    ▼
                              Merge results
```

### Phase 1: Classification

A **TEXT\_UNDERSTANDING** node receives the document and classifies it into one of the known types. The classification prompt constrains the output to an enumerated list, so the Condition node can route deterministically.

### Phase 2: Type-specific extraction

Each branch contains a **TEXT\_EXTRACTION** node (using the Extract Data from File capability) configured with:

* A **prompt** tailored to that document type, instructing the model which fields to look for
* A **response schema** defining the exact JSON structure expected for that type
* **Extraction strategy** settings optimized for the document format (text-heavy PDFs vs. scanned images)

A merge point downstream collects results from whichever branch executed.

***

## Implementation

### Step 1: Configure the classification node

Add a **TEXT\_UNDERSTANDING** node and configure it to classify the document type.

**Example classification prompt:**

```text theme={"system"}
You are a document classifier. Analyze the provided document and determine its type.

Respond with exactly one of the following values:
- BOL
- INVOICE
- RATE_CONFIRMATION
- LUMPER_RECEIPT
- FUEL_RECEIPT

Base your classification on the document layout, headers, and field labels.
If the document does not match any known type, respond with UNKNOWN.
```

**Example response schema:**

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "enum": ["BOL", "INVOICE", "RATE_CONFIRMATION", "LUMPER_RECEIPT", "FUEL_RECEIPT", "UNKNOWN"]
    },
    "confidence": {
      "type": "number",
      "description": "Classification confidence between 0 and 1"
    }
  },
  "required": ["document_type", "confidence"]
}
```

### Step 2: Add the Condition node

Add a **Condition** node after the classification node. Configure branches based on the `document_type` value:

| Branch            | Condition                              | Target                               |
| ----------------- | -------------------------------------- | ------------------------------------ |
| BOL               | `document_type == "BOL"`               | TEXT\_EXTRACTION (BOL)               |
| Invoice           | `document_type == "INVOICE"`           | TEXT\_EXTRACTION (Invoice)           |
| Rate confirmation | `document_type == "RATE_CONFIRMATION"` | TEXT\_EXTRACTION (Rate confirmation) |
| Lumper receipt    | `document_type == "LUMPER_RECEIPT"`    | TEXT\_EXTRACTION (Lumper receipt)    |
| Fuel receipt      | `document_type == "FUEL_RECEIPT"`      | TEXT\_EXTRACTION (Fuel receipt)      |
| Default           | `document_type == "UNKNOWN"`           | Manual review queue                  |

### Step 3: Configure type-specific extraction nodes

Each branch gets its own **TEXT\_EXTRACTION** node with a prompt and schema optimized for that document type. The Extract Data from File capability handles PDFs, images (via OCR), and other supported file types automatically.

<Tabs>
  <Tab title="BOL (Bill of Lading)">
    **Prompt:**

    ```text theme={"system"}
    Extract all relevant fields from this Bill of Lading document.
    Pay special attention to carrier information, shipment details, and freight charges.
    If a field is not present, return null for that field.
    ```

    **Response schema:**

    ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "bol_number": { "type": "string" },
        "carrier": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "mc_number": { "type": "string" },
            "scac_code": { "type": "string" }
          }
        },
        "shipper": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "address": { "type": "string" },
            "city": { "type": "string" },
            "state": { "type": "string" },
            "zip": { "type": "string" }
          }
        },
        "consignee": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "address": { "type": "string" },
            "city": { "type": "string" },
            "state": { "type": "string" },
            "zip": { "type": "string" }
          }
        },
        "ship_date": { "type": "string" },
        "delivery_date": { "type": "string" },
        "pieces": { "type": "integer" },
        "weight": { "type": "number" },
        "freight_charges": { "type": "number" }
      }
    }
    ```
  </Tab>

  <Tab title="Invoice">
    **Prompt:**

    ```text theme={"system"}
    Extract all fields from this invoice document.
    Capture line items as an array. Extract totals, tax amounts, and payment terms.
    If a field is not present, return null for that field.
    ```

    **Response schema:**

    ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "invoice_number": { "type": "string" },
        "invoice_date": { "type": "string" },
        "due_date": { "type": "string" },
        "vendor_name": { "type": "string" },
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "description": { "type": "string" },
              "quantity": { "type": "number" },
              "unit_price": { "type": "number" },
              "amount": { "type": "number" }
            }
          }
        },
        "subtotal": { "type": "number" },
        "tax": { "type": "number" },
        "total": { "type": "number" },
        "payment_terms": { "type": "string" }
      }
    }
    ```
  </Tab>

  <Tab title="Rate confirmation">
    **Prompt:**

    ```text theme={"system"}
    Extract all fields from this rate confirmation document.
    Focus on load details, rate amounts, pickup and delivery information.
    If a field is not present, return null for that field.
    ```

    **Response schema:**

    ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "confirmation_number": { "type": "string" },
        "load_number": { "type": "string" },
        "broker_name": { "type": "string" },
        "carrier_name": { "type": "string" },
        "rate_amount": { "type": "number" },
        "pickup_date": { "type": "string" },
        "pickup_location": { "type": "string" },
        "delivery_date": { "type": "string" },
        "delivery_location": { "type": "string" },
        "equipment_type": { "type": "string" },
        "commodity": { "type": "string" }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Keep schemas as flat as possible for simple document types (like fuel receipts and lumper receipts). Reserve nested objects for complex types that genuinely have grouped fields (like BOL with shipper/consignee blocks).
</Tip>

***

## Configuration reference

| Component                | Node type                                 | Key settings                                                        |
| ------------------------ | ----------------------------------------- | ------------------------------------------------------------------- |
| **Classifier**           | TEXT\_UNDERSTANDING                       | Prompt with enumerated types, constrained response schema           |
| **Router**               | Condition                                 | Branch per document type, default branch for unknown types          |
| **Extractor (per type)** | TEXT\_EXTRACTION (Extract Data from File) | Type-specific prompt, tailored response schema, extraction strategy |
| **Merge**                | Merge / End node                          | Collects output from whichever branch executed                      |

<Info>
  The TEXT\_EXTRACTION node uses the **Extract Data from File** capability, which supports PDFs, DOCX, XLSX, PPTX, and image formats (JPG, PNG, TIFF). Images are automatically converted to PDF before processing via OCR.
</Info>

***

## Scaling to many document types

This pattern scales well because adding a new document type requires only:

1. Adding the new type to the classification prompt's enumerated list
2. Adding a new branch in the Condition node
3. Adding a new TEXT\_EXTRACTION node with the type-specific prompt and schema

No existing branches are modified. This makes the pattern suitable for domains with dozens of document types.

| Domain        | Example document types                                                                                                      |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Logistics** | BOL, invoice, rate confirmation, lumper receipt, fuel receipt, proof of delivery, customs declaration                       |
| **Mortgage**  | Product sheets, income statements, bank statements, tax returns, appraisal reports, title documents, regulatory disclosures |
| **Insurance** | Claims forms, medical records, police reports, repair estimates, coverage declarations                                      |

***

## Variations

### Parallel extraction

Instead of classifying first, run extraction for all document types simultaneously and pick the result with the highest confidence. This trades compute cost for lower latency and avoids classification errors.

<Info>
  Parallel extraction works best when you have a small number of document types (under 5). Beyond that, the cost of running every extractor on every document becomes impractical.
</Info>

### Hierarchical classification

For large document sets, classify in two stages: first into a broad category (financial, shipping, legal), then into a specific type within that category. This reduces the number of options the classifier evaluates at each stage.

```text theme={"system"}
Document
  │
  ▼
TEXT_UNDERSTANDING (broad category)
  │
  ├──► TEXT_UNDERSTANDING (financial subtypes) ──► Condition ──► Extractors
  ├──► TEXT_UNDERSTANDING (shipping subtypes)  ──► Condition ──► Extractors
  └──► TEXT_UNDERSTANDING (legal subtypes)     ──► Condition ──► Extractors
```

### Confidence fallback

Add a confidence threshold to the classification step. If the classifier returns a confidence below the threshold, route the document to a manual classification queue instead of risking an incorrect extraction.

```text theme={"system"}
Condition logic:
  confidence >= 0.8  → route to type-specific extractor
  confidence < 0.8   → route to manual classification
```

<Tip>
  Start with a confidence threshold of 0.8 and adjust based on your observed accuracy. Track classification accuracy over time to identify document types that need prompt refinement.
</Tip>

***

## Related resources

<CardGroup>
  <Card title="Patterns overview" icon="puzzle-piece" href="./overview">
    All available AI patterns and how to combine them
  </Card>

  <Card title="AI node types" icon="diagram-project" href="../agent-builder/node-types">
    Reference for TEXT\_UNDERSTANDING, TEXT\_EXTRACTION, and other node types
  </Card>

  <Card title="Extract Data from File" icon="file-lines" href="../agent-builder/extract-data-from-file">
    Configuration guide for the Extract Data from File node
  </Card>

  <Card title="AI comparison and reconciliation" icon="code-compare" href="./ai-comparison-reconciliation">
    Compare extracted data against system-of-record values
  </Card>
</CardGroup>


# Hybrid AI + business rules
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/hybrid-ai-rules

Combine AI extraction and understanding with deterministic business logic for auditable, explainable decision-making.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

## When to use

Use this pattern when your workflow requires both AI capabilities (extracting data from unstructured documents, classifying items with fuzzy matching, generating natural language reports) and deterministic business logic (financial formulas, eligibility checks, compliance scoring). The key requirement is **auditability** — you need to trace exactly how a decision was reached, which means the AI handles what humans cannot codify as rules, and business rules handle everything else.

Common scenarios:

* Financial product eligibility where income data comes from scanned documents but calculations must follow exact regulatory formulas
* Insurance underwriting that extracts risk factors from free-text medical reports, then applies deterministic scoring tables
* Procurement workflows that classify vendor proposals with AI, then rank them using weighted scoring matrices

Without this pattern, you face two bad options: pure AI (fast but opaque, hard to audit) or pure rules (auditable but unable to handle unstructured input).

***

## Architecture

The pattern alternates between AI nodes and Script/Business Rule nodes in a pipeline:

```
Documents / unstructured input
    |
    v
AI EXTRACTION
(extract structured data from documents)
    |
    v
BUSINESS RULES
(deterministic calculations, formulas)
    |
    v
AI UNDERSTANDING
(fuzzy matching, qualitative filtering)
    |
    v
BUSINESS RULES
(scoring, ranking, normalization)
    |
    v
AI GENERATION
(produce human-readable report)
    |
    v
Final output (structured data + report)
```

Each AI node produces structured JSON output that feeds directly into the next Script node. Each Script node produces deterministic, reproducible results that feed into the next AI node. This alternating structure means every decision point is either fully deterministic (and logged) or clearly marked as AI-assisted (with the prompt and response recorded).

<Info>
  The alternating AI-then-rules structure creates a natural audit trail. For any final decision, you can trace backwards: which AI extraction produced the input values, which formula computed the result, and which AI classification influenced the filtering. This is critical for regulated industries where decisions must be explainable.
</Info>

***

## Implementation

### AI vs. business rule responsibilities

The core principle is a clean separation: AI handles what cannot be expressed as deterministic rules, and business rules handle everything that can.

| Responsibility                                                               | Handled by                       | Why                                              |
| ---------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------ |
| Extract income, debts, employment data from bank statements                  | **AI** (TEXT\_EXTRACTION)        | Unstructured documents, varying formats          |
| Compute monthly payment (PMT), debt-to-income ratio                          | **Business rules** (Script node) | Exact financial formulas, must be auditable      |
| Filter products by qualitative criteria (loan type, sustainability features) | **AI** (TEXT\_UNDERSTANDING)     | Fuzzy matching, natural language descriptions    |
| Normalize scores, rank products, apply weight matrices                       | **Business rules** (Script node) | Deterministic scoring, reproducible results      |
| Generate consultant report with recommendations                              | **AI** (TEXT\_GENERATION)        | Natural language output, professional formatting |

***

### Step 1: AI extraction

Configure a TEXT\_EXTRACTION node to pull structured data from unstructured documents. The node receives bank-specific rule documents and extracts the parameters your business rules need.

#### Prompt

```text theme={"system"}
Extract the following financial parameters from the provided bank rule document:

- income_weights: object mapping income source types to their weight factors
- debt_factors: object mapping debt types to their monthly burden factors
- max_ltv: maximum loan-to-value ratio (as decimal)
- min_income_threshold: minimum gross monthly income required
- supported_currencies: array of accepted currency codes
- special_conditions: any additional eligibility conditions described in the document

Return a JSON object with these fields. Use null for any parameter not found in the document.
```

#### Response Schema

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "income_weights": {
      "type": "object",
      "description": "Income source type to weight factor mapping"
    },
    "debt_factors": {
      "type": "object",
      "description": "Debt type to monthly burden factor mapping"
    },
    "max_ltv": {
      "type": "number"
    },
    "min_income_threshold": {
      "type": "number"
    },
    "supported_currencies": {
      "type": "array",
      "items": { "type": "string" }
    },
    "special_conditions": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["income_weights", "debt_factors", "max_ltv", "min_income_threshold"]
}
```

| Setting         | Value                                    |
| --------------- | ---------------------------------------- |
| **Node type**   | `TEXT_EXTRACTION`                        |
| **Input**       | Bank rule document (PDF or text)         |
| **Output key**  | `extractedParams`                        |
| **Temperature** | `0` — extraction should be deterministic |

***

### Step 2: Business rules (calculations)

Add a Script node immediately after the extraction. This node takes the AI-extracted parameters and applies deterministic financial formulas. Because this is a Script node, every calculation is reproducible and auditable.

#### Example script

```javascript theme={"system"}
// Inputs from AI extraction
const params = input.extractedParams.output;
const client = input.clientData;

// Weighted income calculation
let weightedIncome = 0;
for (const [source, amount] of Object.entries(client.incomeSources)) {
  const weight = params.income_weights[source] || 0;
  weightedIncome += amount * weight;
}

// Monthly debt burden
let monthlyDebt = 0;
for (const [debtType, balance] of Object.entries(client.debts)) {
  const factor = params.debt_factors[debtType] || 0.05;
  monthlyDebt += balance * factor;
}

// PMT calculation (monthly payment for a given loan amount)
function computePMT(principal, annualRate, termMonths) {
  const r = annualRate / 12;
  if (r === 0) return principal / termMonths;
  return principal * (r * Math.pow(1 + r, termMonths)) /
         (Math.pow(1 + r, termMonths) - 1);
}

// Debt-to-income ratio
const dti = (monthlyDebt) / weightedIncome;

// Maximum loan amount (iterative solve for PMT <= allowed DTI share)
const maxDtiShare = 0.43; // Standard threshold
const allowablePayment = (maxDtiShare * weightedIncome) - monthlyDebt;
const maxLoan = allowablePayment > 0
  ? allowablePayment * ((Math.pow(1 + client.rate / 12, client.termMonths) - 1) /
    (client.rate / 12 * Math.pow(1 + client.rate / 12, client.termMonths)))
  : 0;

// Currency conversion (if needed)
const loanInClientCurrency = maxLoan * (client.exchangeRate || 1);

output.calculationResults = {
  weightedIncome,
  monthlyDebt,
  dti: Math.round(dti * 10000) / 10000,
  maxLoanAmount: Math.round(loanInClientCurrency),
  meetsIncomeThreshold: weightedIncome >= params.min_income_threshold,
  meetsLtvRequirement: (client.requestedLoan / client.propertyValue) <= params.max_ltv
};
```

<Tip>
  Keep Script nodes focused on a single calculation domain (e.g., financial formulas in one node, scoring in another). This makes each node independently testable and easier to audit.
</Tip>

***

### Step 3: AI understanding (qualitative filtering)

Add a TEXT\_UNDERSTANDING node to filter or classify products based on criteria that do not reduce to simple boolean checks — loan type preferences, sustainability features, qualitative fit.

#### Prompt

```text theme={"system"}
You are a mortgage product filter. Given the client's preferences and a list of available
products, evaluate each product against the qualitative criteria.

Client preferences:
- Loan type preference: {{input.clientData.loanTypePreference}}
- Values sustainability features: {{input.clientData.sustainabilityPreference}}
- Risk tolerance: {{input.clientData.riskTolerance}}

For each product, return:
- product_id: the product identifier
- qualitative_match_score: a number between 0 and 1
- match_reasons: brief explanation of why it matches or does not match
- disqualified: boolean, true if the product is fundamentally incompatible

Only return products where disqualified is false.
```

#### Response Schema

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "filtered_products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": { "type": "string" },
          "qualitative_match_score": { "type": "number" },
          "match_reasons": { "type": "string" },
          "disqualified": { "type": "boolean" }
        },
        "required": ["product_id", "qualitative_match_score", "disqualified"]
      }
    }
  },
  "required": ["filtered_products"]
}
```

| Setting         | Value                                                       |
| --------------- | ----------------------------------------------------------- |
| **Node type**   | `TEXT_UNDERSTANDING`                                        |
| **Input**       | Client preferences + product catalog                        |
| **Output key**  | `filteredProducts`                                          |
| **Temperature** | `0.1` — low but allows minor flexibility for fuzzy matching |

***

### Step 4: Business rules (scoring and ranking)

Add a second Script node to normalize scores and produce a final ranked list. This node combines the deterministic calculation results from Step 2 with the AI qualitative scores from Step 3 into a single weighted ranking.

#### Example script

```javascript theme={"system"}
const calcResults = input.calculationResults;
const aiFiltered = input.filteredProducts.output.filtered_products;

// Scoring weights
const WEIGHT_RATE = 0.35;
const WEIGHT_QUALITATIVE = 0.25;
const WEIGHT_LTV = 0.20;
const WEIGHT_FLEXIBILITY = 0.20;

const scored = aiFiltered.map(product => {
  const details = input.productCatalog.find(p => p.id === product.product_id);
  if (!details) return null;

  // Normalize rate score (lower rate = higher score)
  const rateScore = 1 - (details.rate / 0.10); // Normalize against 10% max

  // LTV score (how close to max allowed)
  const ltvScore = details.maxLtv >= calcResults.dti ? 1.0 : details.maxLtv / calcResults.dti;

  // Flexibility score (prepayment, term options)
  const flexScore = (details.allowsPrepayment ? 0.5 : 0) +
                    (details.flexibleTerm ? 0.5 : 0);

  const totalScore = (rateScore * WEIGHT_RATE) +
                     (product.qualitative_match_score * WEIGHT_QUALITATIVE) +
                     (ltvScore * WEIGHT_LTV) +
                     (flexScore * WEIGHT_FLEXIBILITY);

  return {
    productId: product.product_id,
    bankName: details.bankName,
    totalScore: Math.round(totalScore * 1000) / 1000,
    breakdown: { rateScore, qualitativeScore: product.qualitative_match_score, ltvScore, flexScore },
    matchReasons: product.match_reasons
  };
}).filter(Boolean);

// Sort descending by total score
scored.sort((a, b) => b.totalScore - a.totalScore);

output.rankedProducts = scored.slice(0, 5); // Top 5
output.topRecommendation = scored[0] || null;
```

***

### Step 5: AI generation (report)

Add a TEXT\_GENERATION node at the end to produce a professional consultant report summarizing the analysis and recommendations.

#### Prompt

```text theme={"system"}
You are a professional mortgage consultant. Generate a concise recommendation report
for the client based on the following analysis results.

Client profile:
- Weighted monthly income: {{input.calculationResults.weightedIncome}}
- Debt-to-income ratio: {{input.calculationResults.dti}}
- Maximum eligible loan: {{input.calculationResults.maxLoanAmount}}

Top recommended products (ranked):
{{input.rankedProducts}}

Structure the report as:
1. Executive summary (2-3 sentences)
2. Eligibility assessment (income qualification, DTI status)
3. Top 3 product recommendations with key differentiators
4. Next steps for the client

Use professional financial language. Do not include disclaimers about being an AI.
```

| Setting         | Value                                       |
| --------------- | ------------------------------------------- |
| **Node type**   | `TEXT_GENERATION`                           |
| **Input**       | Calculation results + ranked products       |
| **Output key**  | `consultantReport`                          |
| **Temperature** | `0.3` — allow natural variation in language |

***

## Pipeline summary

| Step | Node type           | Purpose                                                       | Output                               |
| ---- | ------------------- | ------------------------------------------------------------- | ------------------------------------ |
| 1    | TEXT\_EXTRACTION    | Extract income weights, debt factors from bank rule documents | Structured financial parameters      |
| 2    | Script node         | Compute PMT, DTI, max loan amount, currency conversion        | Deterministic calculation results    |
| 3    | TEXT\_UNDERSTANDING | Filter products by qualitative criteria with fuzzy matching   | Scored and filtered product list     |
| 4    | Script node         | Normalize scores, apply weight matrix, rank top products      | Final ranked recommendations         |
| 5    | TEXT\_GENERATION    | Generate professional consultant report                       | Human-readable recommendation report |

***

## Real-world example

The [Mortgage advisor chatbot](../tutorials/mortgage-advisor) tutorial implements this pattern in its product recommendation handler. When a user asks for mortgage product recommendations, the workflow:

1. Extracts financial parameters from each bank's rule documents
2. Computes eligibility using exact financial formulas (PMT, DTI)
3. Filters the product catalog using AI-driven qualitative matching
4. Ranks the remaining products with a deterministic scoring matrix
5. Generates a personalized consultant report

The full pipeline processes 7 banks in parallel using a fan-out structure, then merges results for the final ranking.

***

## Variations

### Human-in-the-loop

Add approval gates after AI steps to let a human reviewer verify the AI output before it feeds into business rules. This is useful during initial deployment or in high-stakes decisions.

```
AI EXTRACTION --> [Human review gate] --> BUSINESS RULES --> AI UNDERSTANDING --> [Human review gate] --> BUSINESS RULES --> AI GENERATION
```

Implement the review gates using User Task nodes in the parent BPMN process. The reviewer sees the AI output and can correct it before the workflow continues.

### Confidence-weighted rules

Instead of treating AI output as binary (pass/fail), feed the AI confidence score into the business rules as a weight. Low-confidence AI extractions trigger stricter thresholds or flag the result for manual review.

```javascript theme={"system"}
// Adjust DTI threshold based on extraction confidence
const extractionConfidence = input.extractedParams.confidence || 1.0;
const baseMaxDti = 0.43;

// Lower confidence = stricter threshold (more conservative)
const adjustedMaxDti = baseMaxDti * extractionConfidence;

output.meetsAdjustedDti = calcResults.dti <= adjustedMaxDti;
output.confidenceAdjustment = {
  original: baseMaxDti,
  adjusted: adjustedMaxDti,
  confidence: extractionConfidence
};
```

### Multi-source comparison

Extend the pattern to process documents from multiple banks or sources in parallel (using the [Fan-out extraction](./fan-out-extraction) pattern), then merge the results into a single comparison matrix before the scoring step. This is the approach used in the mortgage advisor for comparing products across 7 banks.

***

## Related resources

<CardGroup>
  <Card title="AI patterns overview" icon="puzzle-piece" href="./overview">
    All available patterns and how to combine them
  </Card>

  <Card title="Fan-out extraction" icon="arrows-split-up-and-left" href="./fan-out-extraction">
    Parallel document classification and extraction
  </Card>

  <Card title="Mortgage advisor tutorial" icon="building-columns" href="../tutorials/mortgage-advisor">
    Full implementation of hybrid AI + business rules
  </Card>

  <Card title="AI node types" icon="diagram-project" href="../agent-builder/node-types">
    Reference for TEXT\_EXTRACTION, TEXT\_UNDERSTANDING, and TEXT\_GENERATION
  </Card>
</CardGroup>


# Intent classification and routing
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/intent-classification-routing

Classify user input into intent categories and route to specialized handlers. Use the dedicated Intent Classification node (5.6+) for most cases, or the TEXT_UNDERSTANDING + Condition pattern for advanced scenarios.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

## When to use

Use this pattern when your workflow must handle multiple types of user input and respond differently depending on what the user wants. Intent classification is the foundation of any conversational AI app on FlowX — it determines what happens next.

Common scenarios:

* A chatbot that must distinguish greetings from product inquiries from data submissions
* An email triage pipeline that routes messages to different processing branches
* Any multi-turn conversation where the next step depends on user intent

Without intent classification, a workflow can only follow a single linear path regardless of what the user says.

***

## Recommended: Intent Classification node (5.6+)

```
User message
    |
    v
Intent Classification node
(one output port per intent + built-in If No Intent Matches fallback)
    |
    +--> Handler A (e.g., greeting response)
    +--> Handler B (e.g., product inquiry)
    +--> Handler C (e.g., data input)
    +--> If No Intent Matches (fallback, always present)
```

Benefits over the legacy pattern:

* **No Condition node** — each intent gets its own output port automatically
* **Built-in fallback** — `If No Intent Matches` is always-present and can't be accidentally omitted
* **Use Memory** (Chat Driven workflows) — the classifier can factor in the last few turns when resolving ambiguous messages (e.g., "yes", "tell me more")
* **Include Reason for Selection** — the classifier can emit its rationale, useful for tuning labels during development
* **Up to 10 intents per node** — chain multiple Intent Classification nodes for deeper taxonomies

See the [Intent Classification node reference](../agent-builder/intent-classification) for full configuration details.

### When to use the legacy pattern below

The TEXT\_UNDERSTANDING + Condition pattern remains valid for advanced cases the dedicated node does not cover:

* **Confidence-based routing** — branching on a numeric confidence score, not just the winning label
* **Multi-label classification** — one message may match several intents simultaneously; the Condition node can fire multiple downstream paths
* **Custom post-processing** — applying business rules on the raw LLM output before routing (e.g., demoting an intent below a business-defined threshold)

***

## Legacy pattern: TEXT\_UNDERSTANDING + Condition

The pattern follows a detect-then-route structure:

```
User message
    |
    v
TEXT_UNDERSTANDING node
(classifies intent, returns structured JSON)
    |
    v
Condition node (Python expressions)
    |
    +--> Handler A (e.g., greeting response)
    +--> Handler B (e.g., product inquiry)
    +--> Handler C (e.g., data input)
    +--> Fallback (unrecognized intent)
```

The TEXT\_UNDERSTANDING node analyzes the user message and returns a structured JSON object with the detected intent. The Condition node evaluates that output and forks the workflow to the appropriate handler branch.

### Implementation

#### 1. Configure the TEXT\_UNDERSTANDING node

Add a TEXT\_UNDERSTANDING node to your workflow. This node sends the user message to an LLM with a classification prompt and enforces a structured response via a Response Schema.

#### Prompt

The prompt should instruct the LLM to classify the input into one of your defined intent categories. Be explicit about the categories and expected output format.

```text theme={"system"}
You are an intent classifier. Analyze the user message and classify it into exactly one
of the following intent categories:

- GREETING_SMALL_TALK — greetings, pleasantries, general conversation
- PRODUCT_OFFER_INQUIRY — questions about products, services, pricing, or features
- DATA_INPUT_UPDATE — the user is providing or updating personal data, documents, or form fields
- OTHER — anything that does not fit the above categories

Return a JSON object with:
- detected_intent: one of the categories above (exact string)
- confidence_score: a number between 0 and 1
- thought_process: a brief explanation of why you chose this category
- extracted_entities: (optional) any relevant entities found in the message

Do NOT include any text outside the JSON object.
```

<Tip>
  Keep the prompt focused on classification only. Resist adding response generation here — that belongs in the handler branches downstream.
</Tip>

#### Response Schema

Define a Response Schema on the TEXT\_UNDERSTANDING node to enforce structured output. This guarantees the LLM returns valid JSON matching your expected shape.

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "detected_intent": {
      "type": "string",
      "enum": [
        "GREETING_SMALL_TALK",
        "PRODUCT_OFFER_INQUIRY",
        "DATA_INPUT_UPDATE",
        "OTHER"
      ]
    },
    "confidence_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "thought_process": {
      "type": "string"
    },
    "extracted_entities": {
      "type": "object"
    }
  },
  "required": ["detected_intent", "confidence_score", "thought_process"]
}
```

#### Configuration summary

| Setting             | Value                                                                          |
| ------------------- | ------------------------------------------------------------------------------ |
| **Node type**       | `TEXT_UNDERSTANDING`                                                           |
| **Input**           | User message (from Chat Input node or upstream variable)                       |
| **Output key**      | Configure an output key (e.g., `routesKey`) to store the classification result |
| **Response Schema** | JSON schema as shown above                                                     |
| **Temperature**     | `0` or very low — classification should be deterministic                       |

***

#### 2. Configure the Condition node

After the TEXT\_UNDERSTANDING node, add a Condition node to fork the workflow based on the detected intent. Each branch uses a Python expression that evaluates to `True` or `False`.

#### Condition expressions

Use substring matching with the `in` operator for resilience. This handles cases where the LLM wraps the intent in extra whitespace or slightly different formatting.

```python theme={"system"}
# Branch: Greeting / small talk
"GREETING" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))
```

```python theme={"system"}
# Branch: Product inquiry
"PRODUCT_OFFER" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))
```

```python theme={"system"}
# Branch: Data input / update
"DATA_INPUT" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))
```

```python theme={"system"}
# Branch: Fallback (default)
# No condition needed — this is the default/else branch
```

<Warning>
  Always include a fallback branch. Even with a Response Schema, edge cases can produce unexpected intent values. The fallback branch prevents the workflow from stalling.
</Warning>

<Tip>
  Use substring matching (`in` operator) instead of exact equality (`==`). This makes the condition resilient to minor LLM output variations without sacrificing accuracy.
</Tip>

#### Condition node summary

| Branch              | Expression                                                                                        | Routes to                                |
| ------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Greeting**        | `"GREETING" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))`      | Greeting handler                         |
| **Product inquiry** | `"PRODUCT_OFFER" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))` | Product info handler                     |
| **Data input**      | `"DATA_INPUT" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))`    | Data processing handler                  |
| **Fallback**        | Default branch                                                                                    | Generic response or clarification prompt |

***

#### 3. Build handler branches

Each handler branch is a self-contained sub-workflow tailored to the classified intent. Examples:

* **Greeting handler** — responds with a welcome message or continues small talk using a text generation node
* **Product inquiry handler** — queries a knowledge base (see the [Knowledge base RAG](./knowledge-base-rag) pattern) and returns product information
* **Data input handler** — validates and stores user-provided data, then confirms receipt
* **Fallback handler** — asks the user to rephrase or provides a generic help message

After all branches complete their work, they converge back to a shared endpoint (typically a Closing Gateway or End node).

***

## Real-world example

The [Mortgage advisor chatbot](../tutorials/mortgage-advisor) tutorial implements this pattern as its core routing mechanism. User messages are classified into intents such as greeting, product inquiry (mortgage offers), data submission (income, employment), and general questions — then routed to specialized handlers that combine knowledge base lookups, financial calculations, and conversational responses.

***

## Variations

### Binary classification

When you only need to distinguish between two outcomes (e.g., yes/no, relevant/irrelevant), simplify the schema to a single boolean or two-value enum. Use a single Condition branch instead of multiple forks.

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "is_relevant": {
      "type": "boolean"
    },
    "confidence_score": {
      "type": "number"
    }
  },
  "required": ["is_relevant", "confidence_score"]
}
```

### Multi-label classification

Some inputs may belong to multiple categories simultaneously (e.g., a message that both provides data and asks a question). Modify the schema to return an array of intents, and use a ForEach or parallel branching strategy to handle each detected intent.

### Confidence-based routing

Add a confidence threshold check before routing. If the confidence score falls below a threshold (e.g., 0.7), route to a human review queue or ask the user to clarify instead of proceeding with low-confidence automation.

```python theme={"system"}
# High confidence — route normally
float(input.get("routesKey", {}).get("output", {}).get("confidence_score", 0)) >= 0.7
```

```python theme={"system"}
# Low confidence — route to human review or clarification
float(input.get("routesKey", {}).get("output", {}).get("confidence_score", 0)) < 0.7
```

***

## Related resources

<CardGroup>
  <Card title="AI patterns overview" icon="puzzle-piece" href="./overview">
    All available patterns and how to combine them
  </Card>

  <Card title="AI node types" icon="diagram-project" href="../agent-builder/node-types">
    Reference for TEXT\_UNDERSTANDING and other node types
  </Card>

  <Card title="Mortgage advisor tutorial" icon="building-columns" href="../tutorials/mortgage-advisor">
    End-to-end implementation using intent classification
  </Card>

  <Card title="Conversational workflows" icon="comments" href="../conversational-workflows">
    Multi-turn chat with session memory and intent routing
  </Card>
</CardGroup>


# Knowledge base RAG
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/knowledge-base-rag

Ground AI responses in your documents using retrieval-augmented generation with Qdrant vector search and the CUSTOM_AGENT node.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

Retrieval-augmented generation (RAG) lets an AI agent answer questions by searching your documents first, then synthesizing a response from only the retrieved context. This eliminates hallucinations and keeps answers grounded in your actual content.

***

## When to use

Use this pattern when:

* Users need accurate answers drawn from a specific document corpus (product sheets, FAQs, regulatory guides, policies)
* Responses must cite sources and avoid fabrication
* The knowledge changes over time and you want to update documents without retraining a model
* You need domain-specific answers that a general-purpose LLM cannot reliably provide

Do **not** use this pattern when:

* The answer requires real-time data from an external API (use an MCP integration instead)
* The task is classification or extraction rather than open-ended Q\&A (use TEXT\_UNDERSTANDING or TEXT\_EXTRACTION nodes)
* The corpus is very small (fewer than 5 documents) and could fit entirely in a system prompt

***

## Architecture

```
User question
    |
    v
+---------------------------+
| CUSTOM_AGENT node         |
| (with Knowledge Base tool)|
+---------------------------+
    |
    v
+---------------------------+
| Qdrant vector search      |
| (Top K chunks retrieved)  |
+---------------------------+
    |
    v
+---------------------------+
| LLM synthesis             |
| (answer from context only)|
+---------------------------+
    |
    v
Grounded response
```

The CUSTOM\_AGENT node handles the full cycle internally:

1. Analyzes the user query for key terms and intent
2. Searches the connected Qdrant collection for relevant document chunks
3. Receives the top matching chunks ranked by relevance score
4. Synthesizes a response using **only** the retrieved context
5. Returns a grounded answer with source references

***

## Implementation

### Prerequisites

Before configuring the workflow:

* Create a **Knowledge Base** data source in Integration Designer
* Upload your documents (PDFs) to one or more stores in the Knowledge Base
* Wait for automatic chunking and vector indexing to complete

<Info>
  Knowledge Bases use vector embeddings stored in Qdrant for semantic search. Documents are automatically chunked and indexed when uploaded. For details, see the [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview) documentation.
</Info>

### Configure the CUSTOM\_AGENT node

<Steps>
  <Step title="Add a CUSTOM_AGENT node to your workflow">
    In the Agent Builder canvas, drag a **Custom Agent** node into your workflow.
  </Step>

  <Step title="Enable Knowledge Base">
    In the node configuration panel, scroll to the **Knowledge Base** section and enable it. Select the Knowledge Base you created.
  </Step>

  <Step title="Set retrieval parameters">
    Configure how the agent searches your documents.
  </Step>

  <Step title="Write the system prompt">
    Define the agent behavior, retrieval instructions, and response constraints (see prompt template below).
  </Step>
</Steps>

### Retrieval parameters

| Parameter                  | Description                                                                                      | Recommended value              |
| -------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------ |
| **Max. Number of Results** | Number of document chunks retrieved per query (1-10)                                             | `10`                           |
| **Min. Relevance Score**   | Relevance threshold (0-100%). Chunks below this score are excluded                               | `10`                           |
| **Metadata Filters**       | Restrict search using typed conditions. Use the system `source` key to scope to a specific store | No filters (search all stores) |

<Tip>
  Start with a low **Min. Relevance Score** (around 10%) and increase it if the agent returns too much irrelevant context. A high threshold may cause the agent to miss relevant chunks that use different terminology than the query.
</Tip>

### System prompt template

The prompt must instruct the agent to search the Knowledge Base and follow strict grounding rules.

```text theme={"system"}
You are a knowledgeable assistant. Your job is to answer user questions
accurately using ONLY information retrieved from the knowledge base.

INSTRUCTIONS:
1. Analyze the user's question to identify key terms and concepts.
2. Search the knowledge base for relevant information.
3. Synthesize a clear, concise response from ONLY the retrieved context.

STRICT RULES:
- Source fidelity: Base every claim on retrieved document chunks. If the
  knowledge base does not contain relevant information, say: "I don't have
  information about that in my current knowledge base."
- Citations: Reference the source document when possible.
- No hallucinations: Never fabricate information, statistics, or claims
  not present in the retrieved context.
- Stay on topic: Only answer questions related to the knowledge base domain.
```

<Warning>
  The grounding rules are critical. Without explicit instructions to admit gaps in knowledge, the LLM may fall back to its general training data and produce inaccurate answers.
</Warning>

### Input and output

| Direction  | Key                                      | Description                                           |
| ---------- | ---------------------------------------- | ----------------------------------------------------- |
| **Input**  | User message (from chat or process data) | The question to answer                                |
| **Output** | Agent response text                      | The grounded answer synthesized from retrieved chunks |

***

## Real-world example

The **mortgage advisor chatbot** tutorial uses this pattern in its `knowledgeBaseQA` workflow. When the intent classifier detects a `KNOWLEDGE_QA` intent, the router calls a CUSTOM\_AGENT node connected to a Knowledge Base containing mortgage product sheets, regulatory guides, and FAQ documents.

The agent answers questions such as:

* "What is DTI?" (retrieves debt-to-income ratio definition from the FAQ)
* "What are the requirements for a fixed-rate mortgage?" (retrieves eligibility criteria from product sheets)
* "What documents do I need to apply?" (retrieves checklist from the regulatory guide)

<Card title="Mortgage advisor tutorial" icon="building-columns" href="../tutorials/mortgage-advisor">
  Build the full chatbot including intent routing, knowledge base Q\&A, and recommendation generation
</Card>

***

## Variations

### Multi-KB search

Query multiple Knowledge Base collections in a single workflow. Use parallel CUSTOM\_AGENT nodes, each connected to a different Knowledge Base, then merge the results in a downstream node.

**When to use:** Your documents span distinct domains (for example, product documentation and regulatory compliance) that are better organized in separate collections.

### Hybrid search

Combine vector (semantic) search with keyword search for better recall. Set **Search Type** to `Hybrid` (the default in 5.7+) on the CUSTOM\_AGENT or CONTEXT\_RETRIEVAL node. Choose `Semantic` for purely meaning-based retrieval, or `Keyword` when exact-token matches matter more than similarity.

**When to use:** Your documents contain precise terminology (part numbers, policy codes, legal references) where exact keyword matching outperforms semantic similarity alone.

### Re-ranking

Turn on **Re-rank** on the CUSTOM\_AGENT or CONTEXT\_RETRIEVAL node to apply a second-pass ranking step to the retrieved chunks before the LLM sees them. Combined with Hybrid search, re-ranking materially improves answer quality on mixed numeric + natural-language queries.

**When to use:** The initial retrieval returns many marginally relevant chunks and you need higher precision in the final response. Pre-5.7, this required a manual two-step pattern (separate TEXT\_GENERATION node scoring the chunks) — now it's a single toggle.

***

## Best practices

<AccordionGroup>
  <Accordion title="Prepare your documents" icon="file-lines">
    Upload clean, well-structured documents. Remove headers, footers, and boilerplate that add noise. Organize documents into separate stores by topic for easier filtering.
  </Accordion>

  <Accordion title="Test retrieval before building the workflow" icon="flask">
    Use the Knowledge Base test interface to run sample queries and verify that relevant chunks are returned with acceptable relevance scores before wiring the node into a workflow.
  </Accordion>

  <Accordion title="Tune retrieval parameters iteratively" icon="sliders">
    Start with a higher Max. Number of Results (8-10) and a lower Min. Relevance Score (10-20%). Monitor the chunks returned and adjust. Too few results leads to incomplete answers; too many leads to diluted context.
  </Accordion>

  <Accordion title="Keep prompts explicit about limitations" icon="shield">
    Always include instructions for what the agent should do when the Knowledge Base does not contain relevant information. This prevents the LLM from falling back to general knowledge.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Patterns overview" icon="puzzle-piece" href="./overview">
    All available AI patterns
  </Card>

  <Card title="Node types" icon="diagram-project" href="../agent-builder/node-types">
    AI node type reference including Custom Agent
  </Card>

  <Card title="Knowledge Base integration" icon="database" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
    Create and manage Knowledge Bases
  </Card>

  <Card title="Mortgage advisor tutorial" icon="building-columns" href="../tutorials/mortgage-advisor">
    Full tutorial using this pattern
  </Card>
</CardGroup>


# AI patterns
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/overview

Reusable architectural patterns for building AI-powered apps on FlowX.AI.

Patterns are proven solutions to common challenges when building AI apps on FlowX. Each pattern is extracted from production implementations and can be combined to build complex apps.

## Available patterns

<CardGroup>
  <Card title="Intent classification and routing" icon="signs-post" href="./intent-classification-routing">
    Use a TEXT\_UNDERSTANDING node to classify user input and route to specialized handlers. The foundation of any conversational AI app.
  </Card>

  <Card title="Knowledge base RAG" icon="book-open" href="./knowledge-base-rag">
    Ground AI responses in your documents using retrieval-augmented generation with Qdrant vector search and the CUSTOM\_AGENT node.
  </Card>

  <Card title="Fan-out extraction" icon="arrows-split-up-and-left" href="./fan-out-extraction">
    Classify documents by type, then route each to a specialized TEXT\_EXTRACTION node with tailored prompts and schemas. Scale to dozens of document types.
  </Card>

  <Card title="AI comparison and reconciliation" icon="code-compare" href="./ai-comparison-reconciliation">
    Compare AI-extracted document data against system-of-record values and generate structured exception reports with match rates and confidence scores.
  </Card>

  <Card title="Hybrid AI + business rules" icon="scale-balanced" href="./hybrid-ai-rules">
    Combine AI extraction and understanding with deterministic business logic (formulas, eligibility checks, scoring) for auditable decision-making.
  </Card>

  <Card title="Session state management" icon="database" href="./session-state-management">
    Manage conversation history and session state across multi-turn interactions using FlowX Database workflows.
  </Card>
</CardGroup>

***

## How to use patterns

Each pattern page includes:

* **When to use** — the problem it solves and when to reach for it
* **Architecture** — how the workflow nodes connect
* **Implementation** — key configuration: prompts, schemas, fork conditions
* **Real-world example** — where this pattern appears in our tutorials
* **Variations** — common adaptations

Patterns are building blocks. A typical AI app combines 2-4 patterns:

| App type                   | Common pattern combination                                            |
| -------------------------- | --------------------------------------------------------------------- |
| **Conversational advisor** | Intent routing + Knowledge base RAG + Session state + Hybrid AI rules |
| **Document processor**     | Fan-out extraction + AI comparison + Hybrid AI rules                  |
| **Email automation**       | Fan-out extraction + AI comparison + Session state                    |

***

## Pattern origins

These patterns are extracted from two production-grade FlowX apps:

* **Mortgage advisor** — a chatbot that evaluates loan eligibility across 7 banks using conversational AI, document extraction, and financial calculations
* **Logistics document processor** — an email-triggered pipeline that processes 17 document types from carrier emails, reconciles them against a TMS, and surfaces exceptions for review

See the [Tutorials](../tutorials/overview) for full implementations.

***

## Related resources

<CardGroup>
  <Card title="Tutorials" icon="graduation-cap" href="../tutorials/overview">
    End-to-end implementations using these patterns
  </Card>

  <Card title="Node types" icon="diagram-project" href="../agent-builder/node-types">
    AI node type reference
  </Card>

  <Card title="Conversational workflows" icon="messages" href="../conversational-workflows">
    Multi-turn chat with session memory
  </Card>

  <Card title="Using agents" icon="play" href="../using-agents/overview">
    Integration and deployment options
  </Card>
</CardGroup>


# Session state management
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/session-state-management

Manage conversation history and session state across multi-turn interactions using FlowX Database workflows.

<Warning>
  **Agent Builder** is currently in preview and is subject to change. Features described in this pattern may evolve in future releases.
</Warning>

## Overview

AI nodes in FlowX workflows are stateless — each invocation starts fresh with no memory of previous turns. For multi-turn conversations such as chatbots, advisors, or guided flows, you need a strategy to persist and reload conversation history between interactions.

This pattern uses a **FlowX Database** data source to store session state, loading it at the start of each turn and saving the updated history after the AI response.

***

## When to use

* Multi-turn chatbots or conversational assistants
* Guided workflows where the AI needs context from earlier steps
* Any scenario where the user returns to a conversation after a delay
* Task-oriented workflows requiring custom memory strategies

***

## Architecture

The session state management pattern follows a read-process-write cycle on every turn:

```
User message
  → Load session (DB read)
    → Inject history into prompt
      → AI processing
        → Append exchange to history
          → Save session (DB write)
            → Response to user
```

Each workflow invocation performs these steps:

1. **Load** — Query the `ChatSessions` data source by `sessionId` to retrieve existing conversation history.
2. **Inject** — Insert the retrieved history into the AI node's operation prompt as context.
3. **Process** — The AI node generates a response informed by the full conversation context.
4. **Append** — Add both the user message and the AI response to the `messages` array.
5. **Save** — Write the updated session back to the data source.

***

## Data model

Create a **FlowX Database** data source named `ChatSessions` with the following schema:

| Field         | Type       | Description                                               |
| ------------- | ---------- | --------------------------------------------------------- |
| **sessionId** | `STRING`   | Unique identifier for the conversation session            |
| **messages**  | `OBJECT[]` | Array of message objects storing the conversation history |

Each entry in the `messages` array follows this structure:

| Field       | Type     | Description                                |
| ----------- | -------- | ------------------------------------------ |
| **role**    | `STRING` | The message author — `user` or `assistant` |
| **content** | `STRING` | The text content of the message            |

Example stored session:

```json theme={"system"}
{
  "sessionId": "sess-a1b2c3d4",
  "messages": [
    { "role": "user", "content": "I want to apply for a mortgage." },
    { "role": "assistant", "content": "I can help with that. What type of property are you looking to finance?" },
    { "role": "user", "content": "A single-family home, around 250,000 EUR." },
    { "role": "assistant", "content": "Great. Do you have a preferred loan term — 15, 20, or 30 years?" }
  ]
}
```

***

## Implementation

<Steps>
  <Step title="Create the ChatSessions data source">
    In the **Integration Designer**, add a new **FlowX Database** data source named `ChatSessions`. Define the `sessionId` (STRING) and `messages` (OBJECT array) fields.
  </Step>

  <Step title="Load session history at workflow start">
    Add a **Query** node at the beginning of your workflow that reads from `ChatSessions`, filtering by the incoming `sessionId`. If no session exists, initialize an empty messages array.
  </Step>

  <Step title="Inject history into the AI node prompt">
    In the AI node's operation prompt, include the loaded conversation history as context. Format the messages array into a readable block:

    ```text theme={"system"}
    Previous conversation:
    User: I want to apply for a mortgage.
    Assistant: I can help with that. What type of property are you looking to finance?
    User: A single-family home, around 250,000 EUR.
    Assistant: Great. Do you have a preferred loan term — 15, 20, or 30 years?

    Current user message: {currentMessage}
    ```

    Use a **Data Operations** node before the AI node to transform the `messages` array into this string format and map it to the prompt input.
  </Step>

  <Step title="Append the new exchange to history">
    After the AI node produces a response, use a **Data Operations** node to append two new entries to the `messages` array:

    ```json theme={"system"}
    [
      { "role": "user", "content": "{currentMessage}" },
      { "role": "assistant", "content": "{aiResponse}" }
    ]
    ```
  </Step>

  <Step title="Save the updated session">
    Add an **Upsert** node that writes the updated session back to the `ChatSessions` data source, using `sessionId` as the key. This ensures new sessions are created automatically and existing ones are updated.
  </Step>
</Steps>

***

## Context window management

Long conversations can exceed the AI model's context window or degrade response quality. Use these strategies to keep history manageable:

### Summarization

For conversations exceeding a threshold (for example, 20 turns), use a separate AI node to generate a summary of older messages. Replace the full history with:

```text theme={"system"}
Summary of earlier conversation:
The user is applying for a 30-year mortgage on a 250,000 EUR single-family home.
They have a 50,000 EUR down payment and prefer a fixed rate.

Recent conversation:
User: What documents do I need to provide?
Assistant: You will need proof of income, bank statements, and a property appraisal.
```

This preserves key context while staying within token limits.

### Token counting

Track approximate token usage for the history block. When it approaches 60-70% of the model's context window, trigger summarization. This leaves sufficient room for the system prompt, current message, and the AI response.

***

## Real-world example

The **Mortgage advisor chatbot** tutorial shows multi-turn advising using the built-in session memory. Use that tutorial for a Chat Driven walkthrough; refer to this pattern if you need a custom memory strategy (sliding window, topic-based, cross-session) for a task-oriented workflow instead.

For the tutorial, see the [Mortgage advisor tutorial](../tutorials/mortgage-advisor).

***

## Variations

### Sliding window

Keep only the last **N** turns (for example, 10) in the prompt context. Older messages remain stored in the database for audit purposes but are not injected into the prompt. This is the simplest approach and works well for short, focused conversations.

### Topic-based memory

Partition conversation history by topic. When the user switches subjects, start a new topic segment while retaining a brief summary of previous topics. This works well for advisor-style bots that cover multiple domains in one session.

### Cross-session memory

Maintain a persistent **user profile** that carries context across separate conversations. Store preferences, decisions, and key facts in a dedicated data source keyed by user ID rather than session ID. Inject a profile summary at the start of each new session so the AI can reference prior interactions.

***

***

## Related resources

<CardGroup>
  <Card title="AI patterns overview" icon="brain" href="./overview">
    All available AI integration patterns
  </Card>

  <Card title="Conversational workflows" icon="comments" href="../conversational-workflows">
    Built-in session memory in FlowX 5.6+
  </Card>

  <Card title="Mortgage advisor tutorial" icon="building-columns" href="../tutorials/mortgage-advisor">
    End-to-end chatbot with session persistence
  </Card>

  <Card title="Intent classification pattern" icon="bullseye" href="./intent-classification">
    Route user messages to specialized handlers
  </Card>
</CardGroup>


# AI Analyst
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-analyst

Builds and optimizes BPMN processes using AI to generate, validate, and enhance workflows based on user-provided documents

## Overview

The AI Analyst is an intelligent agent that transforms various inputs into Business Process Model and Notation (BPMN) processes. It can generate complete workflows from text prompts, images, or documents, as well as modify existing BPMN processes. The agent uses advanced AI to interpret requirements and convert them into structured JSON representations that the FlowX.AI platform can interpret and visualize as proper BPMN diagrams.

<Frame>
  <video />
</Frame>

***

## Key capabilities

The AI Analyst offers two main categories of capabilities:

<CardGroup>
  <Card title="Generate from prompt" icon="keyboard">
    Creates a complete BPMN process based on natural language descriptions. Transforms textual requirements into a structured workflow and produces a JSON representation containing nodes (with name and type) and links between nodes.
  </Card>

  <Card title="Generate from image" icon="image">
    Extracts BPMN process information from uploaded images, identifies swimlanes and components, and processes various image resolutions. Accepts optional text descriptions for additional context.
  </Card>

  <Card title="Generate from document" icon="file-lines">
    Extracts process descriptions from uploaded documents, analyzes textual content to identify workflow components and relationships, and creates a structured representation of the described process.
  </Card>

  <Card title="Generate from BPMN file" icon="file-code">
    Imports and interprets existing BPMN files and converts external BPMN formats into FlowX.AI-compatible representations.
  </Card>

  <Card title="Generate in-between nodes" icon="diagram-project">
    Adds missing steps between existing nodes in a workflow, enhancing process completeness and logical flow.
  </Card>

  <Card title="Generate from node" icon="diagram-next">
    Expands a process by adding subsequent steps after a specified node, allowing incremental development of complex workflows.
  </Card>

  <Card title="Edit existing process" icon="pen-to-square">
    Modifies components of an existing process based on user instruction, updating node properties, connections, or process structure.
  </Card>
</CardGroup>

***

## How it works

The AI Analyst architecture integrates multiple AI components to process different input types and generate standardized BPMN output.

The workflow begins with a user query that gets rewritten for clarity. A quality check determines if more information is needed, in which case a human provides additional context. Once sufficient information is available, the process generation component creates the BPMN workflow, which is then delivered to the user.

<Tabs>
  <Tab title="Generate new">
    ### Generate from prompt

    Creates a complete BPMN process based on natural language descriptions. Transforms textual requirements into a structured workflow and produces a JSON representation containing nodes (with name and type) and links between nodes.

    ```mermaid theme={"system"}
    %%{
      init: {
        'theme': 'base',
        'themeVariables': {
          'primaryColor': '#f1774a',
          'primaryTextColor': '#000',
          'primaryBorderColor': '#000',
          'lineColor': '#6b6b6b',
          'secondaryColor': '#f3b861',
          'tertiaryColor': '#bababa'
        }
      }
    }%%
    graph TD;
        Start([Start]):::primary
        Check_Prompt[Check Prompt]:::secondary
        Classify_Image[Classify Image]:::tertiary
        Generate_Process[Generate Process]:::secondary
        Generate_from_Node[Generate from Node]:::tertiary
        Generate_between_Nodes[Generate between Nodes]:::tertiary
        PostProcessing[PostProcessing]:::secondary
        END([END]):::primary

        subgraph Parallel_Processing [Parallel Processing]
            Process_Swimlanes[Process Swimlanes]:::tertiary
            Split_Image[Split Image]:::tertiary
            Image_Analysis[Image Analysis]:::tertiary
            Generate_Prompt[Generate Prompt]:::tertiary
        end

        Start ==> Check_Prompt;
        Start --> Classify_Image;
        Classify_Image --> Parallel_Processing;
        Parallel_Processing --> Generate_Process;
        Check_Prompt ==> Generate_Process;
        Check_Prompt --> Generate_from_Node;
        Check_Prompt --> Generate_between_Nodes;
        Generate_Process ==> PostProcessing;
        Generate_from_Node --> PostProcessing;
        Generate_between_Nodes --> PostProcessing;
        PostProcessing ==> END;

        %% Styling
        classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
        classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
        classDef tertiary fill:#bababa,stroke:#000,stroke-width:1px,color:#000;
    ```

    ### Generate from image

    Extracts BPMN process information from uploaded images, identifies swimlanes and components in diagram images, and can process various image resolutions (from small \< 4K to large > 8K). Accepts optional text descriptions for additional context and combines visual recognition with language processing for accurate interpretation.

    ```mermaid theme={"system"}
    %%{
      init: {
        'theme': 'base',
        'themeVariables': {
          'primaryColor': '#f1774a',
          'primaryTextColor': '#000',
          'primaryBorderColor': '#000',
          'lineColor': '#6b6b6b',
          'secondaryColor': '#f3b861',
          'tertiaryColor': '#bababa'
        }
      }
    }%%
    graph TD;
        Start([Start]):::primary
        Classify_Image[Classify Image]:::secondary
        Check_Prompt[Check Prompt]:::tertiary
        Generate_Process[Generate Process]:::secondary
        Generate_from_Node[Generate from Node]:::tertiary
        Generate_between_Nodes[Generate between Nodes]:::tertiary
        Post_Processing[Post Processing]:::secondary
        END([END]):::primary

        subgraph Parallel_Processing [Parallel Processing]
            Process_Swimlanes[Process Swimlanes]:::secondary
            Split_Image[Split Image]:::secondary
            Image_Analysis[Image Analysis]:::secondary
            Generate_Prompt[Generate Prompt]:::secondary
        end

        Start ==> Classify_Image;
        Start --> Check_Prompt;
        Classify_Image ==> Parallel_Processing;
        Parallel_Processing ==> Generate_Process;
        Check_Prompt --> Generate_Process;
        Check_Prompt --> Generate_from_Node;
        Check_Prompt --> Generate_between_Nodes;
        Generate_Process ==> Post_Processing;
        Generate_from_Node --> Post_Processing;
        Generate_between_Nodes --> Post_Processing;
        Post_Processing ==> END;

        %% Styling
        classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
        classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
        classDef tertiary fill:#bababa,stroke:#000,stroke-width:1px,color:#000;
        classDef secondary-highlight fill:#f3b861,stroke:#8a2be2,stroke-width:2px,color:#000;
    ```

    ### Generate from document

    Extracts process descriptions from uploaded documents, analyzes textual content to identify workflow components and relationships, and creates a structured representation of the described process.

    <img alt="AI Analyst Diagram - Light Mode" />

    <img alt="AI Analyst Diagram - Dark Mode" />
  </Tab>

  <Tab title="Edit existing">
    ### Generate process from BPMN file

    Imports and interprets existing BPMN files and converts external BPMN formats into FlowX.AI-compatible representations.

    ### Generate in-between nodes

    Adds missing steps between existing nodes in a workflow, enhancing process completeness and logical flow.

    <img alt="AI Analyst Diagram - Light Mode" />

    <img alt="AI Analyst Diagram - Dark Mode" />

    ### Generate from node

    Expands a process by adding subsequent steps after a specified node, allowing incremental development of complex workflows.

    <img alt="AI Analyst Diagram - Light Mode" />

    <img alt="AI Analyst Diagram - Dark Mode" />

    ### Edit existing process

    Modifies components of an existing process based on user instruction, updating node properties, connections, or process structure.

    <img alt="AI Analyst Diagram - Light Mode" />

    <img alt="AI Analyst Diagram - Dark Mode" />
  </Tab>
</Tabs>

***

## How to use

The AI Analyst is accessed through the FlowX.AI Platform interface.

<Steps>
  <Step title="Select the desired capability">
    Choose the appropriate capability from the AI Analyst section based on your input type and goal.
  </Step>

  <Step title="Provide input">
    Supply input in the appropriate format: text prompt, image, document, or BPMN file.
  </Step>

  <Step title="Add additional context">
    Optionally add extra context or requirements to refine the generated output.
  </Step>

  <Step title="Review the generated process">
    Review the generated process in a visual BPMN format to verify it meets your expectations.
  </Step>

  <Step title="Make adjustments">
    Use the "Edit" capabilities to make adjustments if necessary.
  </Step>

  <Step title="Implement the workflow">
    Implement the final workflow in your project.
  </Step>
</Steps>

The interaction follows a human-in-the-loop approach, allowing for quality checks and iterative improvements to ensure the generated process meets requirements.

***

## Best practices

### DO the following

<Card icon="square-check">
  **Be specific about process goals:**
  Clearly state what the process should accomplish, including start and end points, major milestones, and desired outcomes.
</Card>

<Card icon="square-check">
  **Describe key participants and roles:**
  Mention the different stakeholders or departments involved in the process and their responsibilities.
</Card>

<Card icon="square-check">
  **Include decision points:**
  Specify any conditional logic or decision points that might create branches in the workflow.
</Card>

<Card icon="square-check">
  **Provide process constraints:**
  Mention any business rules, regulations, or time constraints that should be incorporated into the process design.
</Card>

### DON'T do these

<Card icon="ban">
  **Don't be too technical with BPMN terms:**
  You don't need to use precise BPMN terminology; the AI Analyst can interpret business language and convert it to appropriate BPMN elements.
</Card>

<Card icon="ban">
  **Don't request subprocess details:**
  The AI Analyst has no knowledge about subprocesses or other platform-specific information not provided in your input.
</Card>

<Card icon="ban">
  **Don't upload low-quality images:**
  When generating from images, ensure the diagram is clear and readable to improve accuracy of the generated process.
</Card>

<Card icon="ban">
  **Don't expect platform-specific optimizations:**
  The AI Analyst generates standard BPMN representations and may not incorporate FlowX.AI platform-specific features automatically.
</Card>

***

## Related resources

<CardGroup>
  <Card title="Agent Builder" icon="robot" href="../agent-builder/overview">
    Build custom AI agents for your business workflows
  </Card>

  <Card title="AI Designer" icon="paintbrush" href="./ai-designer">
    Generate and refine UI components using AI
  </Card>

  <Card title="AI Developer" icon="code" href="./ai-developer">
    Generate business rules and integration logic with AI
  </Card>
</CardGroup>


# AI Assistant
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-assistant

Answers questions about the FlowX.AI platform as well as your organization's business domain based on uploaded documentation.

## Overview

The AI Assistant provides intelligent documentation support for both the FlowX.AI platform and your organization's business domain. It functions as a knowledge hub that can quickly search, retrieve, and synthesize information from both built-in FlowX.AI documentation and custom uploaded documents. You can ask natural language questions and receive well-formatted, accurate answers drawn from up-to-date documentation sources.

<Frame>
  <video />
</Frame>

***

## Key capabilities

The AI Assistant offers specialized content search functionality across different documentation sources:

<CardGroup>
  <Card title="Platform documentation search" icon="magnifying-glass">
    Provides answers to questions about the FlowX.AI platform, its features, configuration options, and best practices. Accesses a comprehensive repository of approximately 1,000 documentation chunks (318,000 tokens).
  </Card>

  <Card title="Custom document support" icon="file-arrow-up">
    Upload your organization's business domain documentation so the assistant can answer domain-specific questions alongside platform queries.
  </Card>

  <Card title="Natural language queries" icon="comments">
    Handles direct questions, keyword searches, or general topic inquiries related to the platform and uploaded documentation.
  </Card>

  <Card title="Formatted responses" icon="file-lines">
    Delivers answers in well-formatted markdown for readability, with rapid response times for most queries. Documentation ingestion takes approximately 12 seconds.
  </Card>
</CardGroup>

***

## How it works

The AI Assistant architecture follows a retrieval-augmented generation approach:

```mermaid theme={"system"}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#f1774a',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#6b6b6b',
      'secondaryColor': '#f3b861',
      'tertiaryColor': '#000'
    }
  }
}%%
graph TD;
    Start([Start]):::primary
    Check_Prompt[Check Prompt]:::secondary
    Rewrite_Query[Rewrite Query]:::secondary
    Retrieve_Documents[Retrieve Documents]:::secondary
    Grade_Documents[Grade Documents]:::secondary
    Generate_Answer[Generate Answer]:::secondary
    Generate_Greetings[Generate Greetings]:::secondary
    END([END]):::primary

    Start --> Check_Prompt;
    Check_Prompt --> Rewrite_Query;
    Check_Prompt --> Generate_Greetings;
    Rewrite_Query --> Retrieve_Documents;
    Retrieve_Documents --> Grade_Documents;
    Grade_Documents --> Generate_Answer;
    Generate_Answer --> END;
    Generate_Greetings --> END;

    %% Styling
    classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
    classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
```

The workflow begins with query refinement, followed by document retrieval and relevance grading. Based on the quality of retrieved information, the system can generate an immediate response, process a more complex response asynchronously, or refuse to answer if no relevant documentation is found.

***

## How to use

The AI Assistant is accessible within the FlowX.AI Platform:

<Steps>
  <Step title="Open the AI Assistant">
    Find the AI Assistant in the help section of the platform interface.
  </Step>

  <Step title="Ask a question">
    Use the chat-based interface to type natural language questions. View responses in real-time with markdown formatting, and follow up with additional questions in a conversational manner.
  </Step>

  <Step title="Upload custom documentation">
    Upload your organization's documentation through the document upload interface in the assistant section. You can select files from your local system or provide URLs to documentation resources.
  </Step>

  <Step title="Reference past conversations">
    Access saved conversations to reference past interactions. The assistant maintains context between sessions.
  </Step>
</Steps>

***

## Best practices

### DO the following

<Card icon="square-check">
  **Be specific with your questions:**
  Clearly articulate what information you need about the FlowX.AI platform or your organization's business domain. The more specific your question, the more precise the answer will be.
</Card>

<Card icon="square-check">
  **Reference platform components:**
  Mention specific features, modules, or functions you're asking about to help the assistant retrieve the most relevant documentation.
</Card>

<Card icon="square-check">
  **Provide context:**
  When asking follow-up questions, include relevant context or reference your previous inquiry to help the assistant understand the conversation flow.
</Card>

<Card icon="square-check">
  **Ask about best practices:**
  The assistant can provide guidance on recommended approaches and implementation strategies based on official documentation.
</Card>

### DON'T do these

<Card icon="ban">
  **Don't ask about undocumented features:**
  The assistant relies on available documentation and may not be able to provide information about unreleased or undocumented functionality.
</Card>

<Card icon="ban">
  **Don't expect troubleshooting of specific implementations:**
  While the assistant can provide general guidance, it cannot debug custom code or analyze specific implementation issues without detailed context.
</Card>

<Card icon="ban">
  **Don't assume complete knowledge:**
  If documentation doesn't cover a particular topic, the assistant may not be able to provide comprehensive information on that subject.
</Card>

<Card icon="ban">
  **Don't ask unrelated questions:**
  The assistant is specialized in FlowX.AI platform and your organization's business domain documentation and may not provide accurate answers on unrelated topics.
</Card>

***

## Related resources

<CardGroup>
  <Card title="Agent Builder overview" icon="hammer" href="../agent-builder/overview">
    Create and configure custom AI agents for your organization
  </Card>

  <Card title="AI Analyst" icon="chart-mixed" href="./ai-analyst">
    Assists with process analysis and optimization recommendations
  </Card>

  <Card title="AI Designer" icon="pen-ruler" href="./ai-designer">
    Helps design and build UI components and process flows
  </Card>
</CardGroup>


# AI Designer
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-designer

Convert natural language prompts, Figma designs, or sketches into complete UI layouts with validations and data models.

## Overview

The AI Designer is a tool that transforms design concepts into functional UI components for the FlowX.AI platform. Whether you start with a text description, an image of a design, or a form structure, the AI Designer can generate complete, interactive UI layouts that are immediately usable in your apps. It also handles mapping UI elements to your data model and can modify existing designs based on natural language instructions, significantly accelerating the UI development process.

***

## Key capabilities

The AI Designer offers two main categories of capabilities:

### Generate new UI

<CardGroup>
  <Card title="Generate UI from text" icon="keyboard">
    Creates complete UI layouts based on natural language descriptions. Interprets design requirements and converts them into structured UI elements, maps generated UI components to data model entities when available, produces JSON representations that are automatically parsed into FlowX.AI components, and validates that prompts are UI-related before proceeding with generation.
  </Card>

  <Card title="Generate UI from image" icon="image">
    Extracts UI designs from uploaded images (sketches, mockups, screenshots). Works with hand-drawn sketches, Figma designs, or other visual UI representations. Processes complex images by splitting them into sections for parallel analysis, reconstructs the visual design as functional FlowX.AI UI components, and supports additional textual context to guide the interpretation.
  </Card>

  <Card title="Generate UI from form" icon="rectangle-list">
    Creates structured form interfaces based on form descriptions or requirements. Automatically adds appropriate validations for form fields, organizes form elements in a logical, user-friendly layout, and connects form fields to the corresponding data model properties.
  </Card>

  <Card title="Edit UI from text" icon="pen-to-square">
    Modifies specific containers or cards in existing UI designs. Updates layouts, components, or properties based on natural language instructions. Preserves the structure and functionality of unmodified UI elements, maintains data model connections while implementing requested changes, and validates that edit requests are UI-related before applying modifications.
  </Card>
</CardGroup>

***

## How it works

The AI Designer integrates visual recognition and natural language processing to transform various inputs into structured UI representations.

```mermaid theme={"system"}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#f1774a',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#6b6b6b',
      'secondaryColor': '#f3b861',
      'tertiaryColor': '#bababa'
    }
  }
}%%
graph TD;
    Start([Start]):::primary
    Check_Prompt[Check Prompt]:::secondary
    Classify_Image[Classify Image]:::tertiary
    Edit_Interface[Edit Interface]:::tertiary
    Design_UI[Design UI]:::secondary
    Map_to_Data_Model[Map to Data Model]:::secondary
    END([END]):::primary

    subgraph Parallel_Processing [Parallel Processing]
        Extract_Sections[Extract Sections]:::tertiary
        Component_Identification[Component Identification]:::tertiary
        Map_Components[Map Components]:::tertiary
        Grid_Correction[Grid Correction]:::tertiary
        Validate_Layout[Validate Layout]:::tertiary
    end

    Start --> Check_Prompt;
    Start --> Classify_Image;
    Check_Prompt --> Edit_Interface;
    Check_Prompt --> Design_UI;
    Edit_Interface --> Design_UI;
    Classify_Image --> Parallel_Processing;
    Parallel_Processing --> Design_UI;
    Design_UI --> Map_to_Data_Model;
    Map_to_Data_Model --> END;

    %% Styling
    classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
    classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
    classDef tertiary fill:#bababa,stroke:#000,stroke-width:1px,color:#000;
```

The workflow begins with user input being categorized and processed based on its type. All inputs undergo validation to ensure they describe UI elements. For valid requests, the UI Generator creates the appropriate components, which are then mapped to the data model if available. The final output is compiled into a JSON representation that the FlowX.AI platform can interpret and display as a functional UI.

***

## How to use

The AI Designer is accessed through the FlowX.AI Platform interface.

<Steps>
  <Step title="Access the AI Designer">
    Open the AI Designer from the platform's design tools section.
  </Step>

  <Step title="Select the desired capability">
    Choose between **Generate** or **Edit** mode depending on whether you are creating a new UI or modifying an existing one.
  </Step>

  <Step title="Provide input in the appropriate format">
    * Text description for generating or editing UI
    * Image upload for visual-based UI generation
    * Form structure for form-specific UI creation
  </Step>

  <Step title="Link a data model (optional)">
    Optionally link to an existing data model to enable automatic field mapping.
  </Step>

  <Step title="Preview the generated UI">
    Preview the generated UI components in real-time.
  </Step>

  <Step title="Make adjustments if necessary">
    Use the **Edit** capability to refine and adjust the generated UI through natural language instructions.
  </Step>

  <Step title="Implement the final UI">
    Implement the final UI components in your app.
  </Step>
</Steps>

The agent performs validation checks to ensure inputs are appropriate for UI generation, providing helpful feedback when adjustments are needed.

***

## Best practices

### DO the following

<Card icon="square-check">
  **Specify a type of screen:**
  This means specifying a signup screen, a profile page or anything else that you want to add to your design. Use a context
</Card>

<Card icon="square-check">
  **Add extra context:**
  If designing a user bank app UI, and you want a screen solely about my expenses, include this in your prompt. For example, '`A expenses page that tracks a list of expenses that includes merchant value and transaction date`'. This ensures a tailored screen generation focused on expense-related content.
</Card>

<Card icon="square-check">
  **Describe user interactions:**
  Explain how users should interact with the UI, including any specific workflows, validation requirements, or dynamic behaviors the UI should support.
</Card>

<Card icon="square-check">
  **Have fun and be creative:**
  Most importantly, unleash creativity in your prompts. See what you can generate that will make your UI design stand out from the rest. The screen designer agent has a multitude of capabilities, so make sure to try them out.
</Card>

### DON'T do these

<Card icon="ban">
  **Don't specify colors:**
  The single-screen generator cannot create a new design screen in a different color. However, it is easy to switch up the colors of your generated screen using theming feature.
</Card>

<Card icon="ban">
  **Don't describe multiple screens**
  The screen generator can only generate one type of screen at once. So if you use a prompt referring to two different screens, only one type will be generated.
</Card>

<Card icon="ban">
  **Don't mention a different device:**
  The AI agents don't understand designing in different design screens. So if you want a different device design screen, check in UI designer how your generated design looks on different platforms (Mobile / Web).
</Card>

<Card icon="ban">
  **Don't expect platform-specific knowledge:**
  The AI Designer has no knowledge about other nodes or information in your project beyond what you provide in your prompt or the associated data model.
</Card>

***

## Related resources

<CardGroup>
  <Card title="Agent Builder" icon="hammer" href="../agent-builder/overview">
    Overview of AI agents and the Agent Builder
  </Card>

  <Card title="AI Analyst" icon="magnifying-glass-chart" href="./ai-analyst">
    Automate process analysis and optimization
  </Card>

  <Card title="AI Developer" icon="code" href="./ai-developer">
    Generate business rules and integration logic
  </Card>
</CardGroup>


# AI Developer
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-developer

Generate specific business rules or code expressions from natural language prompts, without manual coding.

## Overview

The AI Developer is an intelligent agent that transforms natural language descriptions into functional code. It helps developers generate business rules, JavaScript expressions, and test data without requiring manual coding. The agent can also edit existing code, provide explanations, and translate between programming languages, significantly accelerating the development process.

<Frame>
  <video />
</Frame>

***

## Key capabilities

The AI Developer offers two main categories of capabilities:

### Generate new code

<CardGroup>
  <Card title="Generate Business Rule" icon="code">
    Transforms natural language descriptions into code using the data model as context. Supports JavaScript, Python, and MVEL. Produces clean, functional business rule code based on text prompts.
  </Card>

  <Card title="Generate Business Rule from Document" icon="file-code">
    Extracts business rule definitions from uploaded documents. Identifies relevant text on each page that describes business rules, summarizes and presents the information to users in a dropdown, and generates corresponding code based on the selected rule description.
  </Card>

  <Card title="Generate (un)Hide JavaScript Expression" icon="eye-slash">
    Creates JavaScript expressions for conditional visibility of elements. Uses the data model as context for proper variable references.
  </Card>

  <Card title="Generate Computed JavaScript Expression" icon="calculator">
    Produces JavaScript code for calculated or derived values. Uses the data model to ensure proper variable referencing.
  </Card>

  <Card title="Generate Custom Component" icon="code-branch">
    Generates a React Custom Component bundle (JSX, CSS, `package.json`, and sample input data) from a natural-language description. A sample input field lets you supply preview data so the generated component renders meaningfully on first run.
  </Card>
</CardGroup>

### Edit existing code

<CardGroup>
  <Card title="Edit Existing Business Rule" icon="pen-to-square">
    Modifies existing code based on natural language instructions. Uses the data model as context for accurate updates.
  </Card>

  <Card title="Edit Custom Component" icon="wand-magic-sparkles">
    Iterates on an existing Custom Component bundle through the same conversation. The agent keeps the component context across turns and updates JSX, CSS, `package.json`, or sample input data as requested.
  </Card>

  <Card title="Fix / Explain Code" icon="wrench">
    Fixes errors in business rules based on error logs. Provides clear explanations of what the code does.
  </Card>

  <Card title="Translate Code Between Languages" icon="language">
    Converts business rules from one language to another. Maintains functionality while adapting to language-specific syntax.
  </Card>
</CardGroup>

***

## How to use

The AI Developer is accessible through the FlowX.AI Platform interface. You can:

<Steps>
  <Step title="Select the desired capability">
    Choose the capability you need from the AI Developer section.
  </Step>

  <Step title="Provide instructions or upload documents">
    Provide natural language instructions or upload relevant documents.
  </Step>

  <Step title="Specify programming language preferences">
    Specify programming language preferences when applicable.
  </Step>

  <Step title="Review and implement the generated code">
    Review the generated code and implement it in your process.
  </Step>
</Steps>

For document-based generation, you can upload documents, view extracted rule descriptions in a dropdown, select the rule you want to generate, and receive the corresponding code.

***

## How it works

The AI Developer architecture integrates large language models with the FlowX.AI Platform to convert natural language to code.

```mermaid theme={"system"}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#f1774a',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#6b6b6b',
      'secondaryColor': '#f3b861',
      'tertiaryColor': '#000'
    }
  }
}%%
graph TD;
    Start([Start]):::primary

    subgraph DI_Platform_process [DI Platform process]
        Classify_Document[Classify Document]:::secondary
        Summarize[Summarize]:::secondary
        Identify_process[Identify process]:::secondary
        Extract_Prompt[Extract Prompt]:::secondary
    end

    Generate_Business_rule[Generate Business rule]:::secondary
    END([END]):::primary

    Start --> DI_Platform_process;
    DI_Platform_process --> Generate_Business_rule;
    Generate_Business_rule --> END;

    %% Styling
    classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
    classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
```

***

## Best practices

### ✅ DO the following

<Card icon="square-check">
  **Be specific with your requirements:**
  Clearly state what the business rule should accomplish, including conditions, actions, and expected outcomes.
</Card>

<Card icon="square-check">
  **Reference data model elements:**
  Mention specific data fields or entities that the code should interact with to ensure proper context.
</Card>

<Card icon="square-check">
  **Specify the programming language:**
  Always indicate whether you need JavaScript, Python, or another supported language for your code generation.
</Card>

<Card icon="square-check">
  **Provide edge cases:**
  Mention special conditions or exceptions that the business rule should handle to ensure reliable code.
</Card>

### ⛔ **DON'T** do these

<Card icon="ban">
  **Don't be vague:**
  Avoid ambiguous descriptions that can lead to incorrect implementation. Be precise about the logic you need.
</Card>

<Card icon="ban">
  **Don't reference external systems:**
  The AI Developer has no knowledge of external systems not defined in the provided context.
</Card>

<Card icon="ban">
  **Don't skip defining variables:**
  Make sure to define all variables or data fields that your business rule will use.
</Card>

<Card icon="ban">
  **Don't expect platform-specific knowledge:**
  The agent doesn't know about keys or information not defined in the data model or provided context.
</Card>

***

## Related resources

<CardGroup>
  <Card title="Agent Builder" icon="robot" href="../../ai-platform/ai-agents/agent-builder">
    Build and configure custom AI agents for your business needs
  </Card>

  <Card title="AI Analyst" icon="magnifying-glass-chart" href="./ai-analyst">
    Generate process definitions and data models from natural language descriptions
  </Card>

  <Card title="AI Designer" icon="paintbrush" href="./ai-designer">
    Automatically generate UI components and screen layouts from process definitions
  </Card>
</CardGroup>


# Config-time agents
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/overview

AI agents built into FlowX Designer that help you create processes, UIs, and business rules faster.

Config-time agents are AI assistants embedded directly in FlowX Designer. They help developers and business analysts build applications faster by automating repetitive tasks and providing intelligent suggestions.

<img alt="Config-time agents architecture" />

<img alt="Config-time agents architecture" />

***

## Available agents

<CardGroup>
  <Card title="Analyst" icon="magnifying-glass-chart" href="./ai-analyst">
    Build and optimize BPMN processes using AI to generate, validate, and enhance workflows
  </Card>

  <Card title="Assistant" icon="message-bot" href="./ai-assistant">
    Answer questions about FlowX platform and your organization based on documentation
  </Card>

  <Card title="Designer" icon="palette" href="./ai-designer">
    Convert natural language prompts, Figma designs, or sketches into UI layouts
  </Card>

  <Card title="Developer" icon="code" href="./ai-developer">
    Generate business rules and code expressions using natural language
  </Card>
</CardGroup>

***

## Access AI in FlowX Designer

Use **Cmd/Ctrl+K** anywhere in FlowX Designer to open the Command Palette and access AI features.

<Frame>
  ![Command Palette](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/command_palette.png)
</Frame>

You can also look for the **✨ icon** throughout the interface to find AI-powered features.

***

## LLM flexibility

Config-time agents support multiple LLM deployment options:

| Option              | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| **Custom models**   | Run your own LLM models through the model registry            |
| **Internal LLMs**   | Connect to your organization's LLMs via OpenAI-compatible API |
| **Cloud providers** | Use OpenAI, Google, Microsoft, Anthropic, or other providers  |

Access to LLMs can be configured through a proxy or gateway. Configure endpoints via environment variables.

***

## Related resources

<CardGroup>
  <Card title="AI in FlowX" icon="hand-sparkles" href="../ai-in-flowx">
    Overview of all AI capabilities
  </Card>

  <Card title="Agent Builder" icon="hammer" href="../agent-builder/overview">
    Create custom business agents
  </Card>
</CardGroup>


# Customer onboarding with KYC
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/customer-onboarding

Build a multi-step customer onboarding process with identity verification, document generation, manual review routing, and email notifications.

In this tutorial, you build a **customer onboarding process** — a BPMN-driven app that collects personal data through multi-step forms, verifies the customer's identity via an external KYC API, generates a welcome letter, and routes failed verifications to a manual review queue.

**What you will build:**

* A **multi-step form** that collects personal details, address, employment, and document uploads
* A **KYC verification** integration that calls an external REST API via an integration workflow
* An **exclusive gateway** that routes the process based on verification results
* A **document generation** step that produces a personalized welcome letter
* A **manual review task** assigned to compliance officers when KYC fails
* An **email notification** sent upon successful onboarding
* A **timer boundary event** for SLA tracking on the review task

**Node types used:** User Task, Send Message Task, Receive Message Task, Exclusive Gateway, Timer Boundary Event

**Patterns demonstrated:** Multi-step form collection, REST API integration via workflows, conditional branching, document generation, task assignment, notification sending

***

## Architecture overview

The process follows a **collect-verify-decide** pattern. Customer data is gathered through a series of user task nodes, sent to a KYC service for verification, and then routed based on the result.

```mermaid theme={"system"}
flowchart TD
    A(("Start")) --> B["User Task:<br/>Personal Information"]
    B --> C["User Task:<br/>Address Details"]
    C --> D["User Task:<br/>Employment & Income"]
    D --> E["User Task:<br/>Document Upload"]
    E --> F["Send Message Task:<br/>Start KYC Check"]
    F -. "Workflow:<br/>kycVerification" .-> F
    F --> G["Receive Message Task:<br/>KYC Result"]
    G --> H{"Exclusive Gateway:<br/>KYC Decision"}
    H -- "PASSED" --> I["Generate Welcome Letter<br/>(Send/Receive Message)"]
    H -- "FAILED / REVIEW" --> J["User Task: Manual Review<br/>⏱ 48h Timer Boundary"]
    J -- "APPROVED" --> I
    J -- "REJECTED" --> K(("End<br/>(Rejected)"))
    I --> L["Send Email Notification<br/>(Send/Receive Message)"]
    L --> M(("End<br/>(Success)"))
```

The main process orchestrates four form steps, delegates KYC verification to an integration workflow, and uses an exclusive gateway to branch into success or manual review paths.

***

## Prerequisites

Before starting, make sure you have:

* Access to a FlowX Designer workspace
* The **Documents Plugin** deployed and configured (for document generation)
* The **Notifications Plugin** deployed and configured (for email sending)
* A document template named `welcomeLetter` created in **Document Templates** (HTML template with placeholders for customer name and date)
* Familiarity with creating processes, user tasks, and actions in FlowX

<Tip>
  If you do not have a real KYC service available, you can simulate one using a mock REST API endpoint (for example, a simple service that returns `PASSED` or `FAILED` based on predefined rules). The integration workflow calls this endpoint the same way it would call a production KYC provider.
</Tip>

***

## Data model

Define the following keys in your process data model. All keys use camelCase and are nested under logical groups.

| Key path                      | Type   | Description                                          |
| ----------------------------- | ------ | ---------------------------------------------------- |
| `customer.firstName`          | String | Customer first name                                  |
| `customer.lastName`           | String | Customer last name                                   |
| `customer.dateOfBirth`        | String | Date of birth (ISO format)                           |
| `customer.nationalId`         | String | National ID or passport number                       |
| `customer.email`              | String | Email address                                        |
| `customer.phone`              | String | Phone number                                         |
| `address.street`              | String | Street address                                       |
| `address.city`                | String | City                                                 |
| `address.postalCode`          | String | Postal code                                          |
| `address.country`             | String | Country (ISO 3166 code)                              |
| `employment.status`           | String | `EMPLOYED`, `SELF_EMPLOYED`, `UNEMPLOYED`, `RETIRED` |
| `employment.employer`         | String | Employer name (if employed)                          |
| `employment.monthlyIncome`    | Number | Monthly income in local currency                     |
| `employment.startDate`        | String | Employment start date                                |
| `documents.identityDoc`       | Object | Uploaded identity document reference                 |
| `documents.proofOfAddress`    | Object | Uploaded proof of address reference                  |
| `kycResult`                   | Object | KYC verification response from external API          |
| `kycResult.status`            | String | `PASSED`, `FAILED`, or `REVIEW`                      |
| `kycResult.score`             | Number | Risk score (0-100)                                   |
| `kycResult.reasons`           | Array  | List of reasons if not passed                        |
| `reviewDecision`              | String | Manual review outcome: `APPROVED` or `REJECTED`      |
| `reviewNotes`                 | String | Notes from the compliance reviewer                   |
| `generatedDocs.welcomeLetter` | Object | Generated welcome letter document reference          |
| `notificationResult`          | Object | Email notification delivery result                   |

***

## Step 1: Create the process definition

<Steps>
  <Step title="Create a new process">
    In FlowX Designer, navigate to your project and create a new process definition named `customerOnboarding`.

    Set the platform to **Web Only** (or **Omnichannel** if you plan to support mobile).
  </Step>

  <Step title="Add swimlanes">
    Create two swimlanes:

    * **Customer** — for the user-facing form steps
    * **BackOffice** — for the manual review task (assigned to a compliance role)

    This ensures the review task is routed to the right team while the customer interacts with the form steps.
  </Step>
</Steps>

<Info>
  For details on configuring swimlanes and role-based access, see the [Swimlanes](../../docs/platform-deep-dive/user-roles-management/swimlanes) documentation.
</Info>

***

## Step 2: Build the data collection forms

Create four **User Task** nodes in the **Customer** swimlane, connected in sequence. Each node represents one step of the onboarding form.

### User Task 1: Personal information

**Node name:** `personalInfo`

Open the UI Designer and add a **Card** with a **Form** containing these fields:

| Component  | Label         | Key                    | Validation             |
| ---------- | ------------- | ---------------------- | ---------------------- |
| Input      | First name    | `customer.firstName`   | Required               |
| Input      | Last name     | `customer.lastName`    | Required               |
| Datepicker | Date of birth | `customer.dateOfBirth` | Required, must be 18+  |
| Input      | National ID   | `customer.nationalId`  | Required               |
| Input      | Email         | `customer.email`       | Required, email format |
| Input      | Phone         | `customer.phone`       | Required               |

Add a **Button** labeled **Next** with an action of type **Save Data** to persist the form values.

### User Task 2: Address details

**Node name:** `addressInfo`

| Component | Label          | Key                  | Validation                           |
| --------- | -------------- | -------------------- | ------------------------------------ |
| Input     | Street address | `address.street`     | Required                             |
| Input     | City           | `address.city`       | Required                             |
| Input     | Postal code    | `address.postalCode` | Required                             |
| Select    | Country        | `address.country`    | Required (populate from enumeration) |

<Tip>
  Use an [enumeration](../../docs/platform-deep-dive/core-extensions/content-management/enumerations) for the country dropdown. Create an enumeration named `countries` with ISO 3166 country codes and labels.
</Tip>

Add **Back** and **Next** buttons. Set `canGoBack: true` on this node so the customer can return to the previous step.

### User Task 3: Employment and income

**Node name:** `employmentInfo`

| Component  | Label             | Key                        | Validation           |
| ---------- | ----------------- | -------------------------- | -------------------- |
| Radio      | Employment status | `employment.status`        | Required             |
| Input      | Employer name     | `employment.employer`      | Required if EMPLOYED |
| Input      | Monthly income    | `employment.monthlyIncome` | Required, numeric    |
| Datepicker | Start date        | `employment.startDate`     | Required if EMPLOYED |

<Info>
  Use a [conditional expression](../../docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field) on the Employer and Start Date fields to show them only when `employment.status` is `EMPLOYED` or `SELF_EMPLOYED`.
</Info>

### User Task 4: Document upload

**Node name:** `documentUpload`

| Component   | Label                                             | Key                        |
| ----------- | ------------------------------------------------- | -------------------------- |
| File Upload | Identity document (passport or ID card)           | `documents.identityDoc`    |
| File Upload | Proof of address (utility bill or bank statement) | `documents.proofOfAddress` |

Add a **Submit** button that triggers the process to move to the KYC verification step.

<Warning>
  Uploaded files are stored via the Documents Plugin. Make sure the plugin is configured with an S3-compatible storage backend before testing this step.
</Warning>

***

## Step 3: Set up the KYC verification integration

The KYC check is handled by an integration workflow that calls an external REST API. This keeps the BPMN process clean and the integration logic reusable.

### Create the data source

<Steps>
  <Step title="Add a RESTful System data source">
    Navigate to **Integrations** > **Data Sources** and create a new data source:

    * **Type:** RESTful System
    * **Name:** KYC Provider
    * **Code:** `kycProvider`
    * **Base URL:** `https://api.{your-kyc-provider}.com/v1`
    * **Authorization:** Bearer Token (configure the token value using a [Configuration Parameter Override](../../docs/projects/runtime/configuration-parameters-overrides) so it differs per environment)
  </Step>

  <Step title="Define the verification endpoint">
    Under the data source, add an endpoint:

    * **Method:** POST
    * **Path:** `/verify`
    * **Body type:** JSON
    * **Request body example:**

    ```json theme={"system"}
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "dateOfBirth": "1990-05-15",
      "nationalId": "AB1234567",
      "country": "GB"
    }
    ```

    * **Response example:**

    ```json theme={"system"}
    {
      "status": "PASSED",
      "score": 92,
      "reasons": [],
      "verificationId": "kyc-20260311-001"
    }
    ```
  </Step>
</Steps>

### Create the integration workflow

<Steps>
  <Step title="Create the workflow">
    Navigate to **Integrations** > **Workflows** and create a new workflow named `kycVerification`.
  </Step>

  <Step title="Add a REST Call node">
    Add a **REST API Call** node connected to the Start node. Configure it to use the `kycProvider` data source and the `/verify` endpoint.

    Map the input variables to the request body:

    ```json theme={"system"}
    {
      "firstName": "${customer.firstName}",
      "lastName": "${customer.lastName}",
      "dateOfBirth": "${customer.dateOfBirth}",
      "nationalId": "${customer.nationalId}",
      "country": "${address.country}"
    }
    ```
  </Step>

  <Step title="Add an End Flow node">
    Add an **End Flow** node after the REST Call. Set the body to pass the response back:

    ```json theme={"system"}
    {
      "output": ${kycResponse}
    }
    ```
  </Step>
</Steps>

<Info>
  For a detailed guide on building integration workflows, see the [Integration Designer](../../docs/platform-deep-dive/integrations/integration-designer) documentation.
</Info>

***

## Step 4: Trigger KYC from the BPMN process

Back in the `customerOnboarding` process, add a **Send Message Task** and a **Receive Message Task** after the `documentUpload` user task.

### Send Message Task: Start KYC check

**Node name:** `sendKycRequest`

Add an action:

* **Action type:** Start Integration Workflow
* **Workflow:** `kycVerification`
* **Input mapping:**

```json theme={"system"}
{
  "customer": "${customer}",
  "address": "${address}"
}
```

* **Trigger:** Automatic
* **Mandatory:** Yes

### Receive Message Task: Receive KYC result

**Node name:** `receiveKycResult`

* **Key Name:** `kycResult`

The workflow output is captured at this key. Subsequent nodes can access `kycResult.status`, `kycResult.score`, and `kycResult.reasons`.

<Info>
  The process waits at the Receive Message Task until the integration workflow completes and returns its output. For details on this pattern, see [Start Integration Workflow Action](../../docs/building-blocks/actions/start-integration-workflow).
</Info>

***

## Step 5: Add the KYC decision gateway

Add an **Exclusive Gateway** node after the `receiveKycResult` node.

**Node name:** `kycDecision`

Configure two outgoing branches:

| Branch          | Condition (JavaScript)          | Target                                   |
| --------------- | ------------------------------- | ---------------------------------------- |
| Passed          | `kycResult.status === "PASSED"` | Go to document generation (success path) |
| Failed / Review | Default (else)                  | Go to manual review task                 |

<Tip>
  Using the default branch for the failure path ensures that any unexpected status value (not just `FAILED`) is routed to human review rather than slipping through.
</Tip>

For details on configuring exclusive gateways, see the [Exclusive Gateway Node](../../docs/building-blocks/node/exclusive-gateway-node) documentation.

***

## Step 6: Build the success path

The success path generates a welcome letter and sends a confirmation email.

### Generate the welcome letter

Add a **Send Message Task** and **Receive Message Task** pair for document generation.

#### Send Message Task: Generate welcome letter

**Node name:** `sendGenerateWelcomeLetter`

Add a **Kafka Send Action** with:

* **Topic:** `ai.flowx.plugin.document.trigger.generate.html.v1`
* **Message body:**

```json theme={"system"}
{
  "documentList": [
    {
      "customId": "welcomeLetter",
      "templateName": "welcomeLetter",
      "language": "en",
      "data": {
        "customerName": "${customer.firstName} ${customer.lastName}",
        "currentDate": "${#now('yyyy-MM-dd')}",
        "accountReference": "${kycResult.verificationId}"
      },
      "includeBarcode": false
    }
  ]
}
```

<Info>
  The `templateName` must match a document template you created in **Document Templates**. Use the WYSIWYG editor to design the welcome letter with placeholders like `{{customerName}}` and `{{currentDate}}`. For details, see [Generating documents from templates](../../docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates).
</Info>

#### Receive Message Task: Receive letter result

**Node name:** `receiveWelcomeLetter`

* **Data stream topic:** use the value from `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT` (default: `ai.flowx.engine.receive.plugin.document.generate.html.results.v1`)
* **Key Name:** `generatedDocs.welcomeLetter`

### Send the confirmation email

Add another **Send Message Task** and **Receive Message Task** pair for notification.

#### Send Message Task: Send email

**Node name:** `sendEmailNotification`

Add a **Kafka Send Action** with:

* **Topic:** `ai.flowx.plugin.notification.trigger.send.notification.v1`
* **Message body:**

```json theme={"system"}
{
  "templateName": "onboardingComplete",
  "channel": "email",
  "receivers": [
    {
      "email": "${customer.email}"
    }
  ],
  "data": {
    "customerName": "${customer.firstName} ${customer.lastName}",
    "subject": "Welcome - Your account is ready"
  }
}
```

<Info>
  Create the `onboardingComplete` notification template in the Notifications Plugin before testing. For configuration details, see the [Notifications Plugin](../../docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview) documentation.
</Info>

#### Receive Message Task: Receive email confirmation

**Node name:** `receiveEmailConfirmation`

* **Data stream topic:** use the value from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` (default: `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1`)
* **Key Name:** `notificationResult`

After this node, add an **End Event** node to close the success path.

***

## Step 7: Build the manual review path

When KYC fails or returns a `REVIEW` status, the process routes to a human reviewer.

### User Task: Manual review

**Node name:** `manualReview`

Place this node in the **BackOffice** swimlane.

Open the UI Designer and create a review interface:

| Component        | Label         | Key                                        | Notes                           |
| ---------------- | ------------- | ------------------------------------------ | ------------------------------- |
| Text             | Customer name | `customer.firstName` + `customer.lastName` | Read-only display               |
| Text             | National ID   | `customer.nationalId`                      | Read-only display               |
| Text             | KYC status    | `kycResult.status`                         | Read-only display               |
| Text             | Risk score    | `kycResult.score`                          | Read-only display               |
| Text             | Reasons       | `kycResult.reasons`                        | Read-only list                  |
| Select           | Decision      | `reviewDecision`                           | Options: `APPROVED`, `REJECTED` |
| Input (textarea) | Notes         | `reviewNotes`                              | Required                        |

Add two buttons:

* **Approve** — sets `reviewDecision` to `APPROVED` and advances
* **Reject** — sets `reviewDecision` to `REJECTED` and advances

<Tip>
  Enable **Update Task Management** on this node so the task appears in the Task Manager inbox for compliance officers. Assign the node to a swimlane with the appropriate role (for example, `COMPLIANCE_REVIEWER`).
</Tip>

### Timer boundary event: SLA escalation

Attach a **Timer Boundary Event** to the `manualReview` node to enforce a 48-hour SLA.

* **Timer type:** Duration
* **Duration:** `PT48H` (ISO 8601 format — 48 hours)
* **Interrupting:** No (non-interrupting — the review can still complete after escalation)

Connect the timer to a **Send Message Task** that sends an escalation notification:

```json theme={"system"}
{
  "templateName": "reviewEscalation",
  "channel": "email",
  "receivers": [
    {
      "email": "${escalation.managerEmail}"
    }
  ],
  "data": {
    "customerName": "${customer.firstName} ${customer.lastName}",
    "hoursOverdue": "48",
    "subject": "Overdue: KYC review pending for 48 hours"
  }
}
```

<Info>
  For details on timer configuration, see [Timer Boundary Event](../../docs/building-blocks/node/timer-events/timer-boundary-event) and [Timer Expressions](../../docs/building-blocks/node/timer-events/timer-expressions).
</Info>

### Review decision gateway

Add a second **Exclusive Gateway** after the `manualReview` node.

**Node name:** `reviewDecisionGateway`

| Branch   | Condition (JavaScript)          | Target                                        |
| -------- | ------------------------------- | --------------------------------------------- |
| Approved | `reviewDecision === "APPROVED"` | Go to document generation (same success path) |
| Rejected | Default (else)                  | Go to rejection End Event                     |

For the **Approved** branch, connect to the same document generation and email notification nodes used in the success path (or duplicate them if your process layout requires separate paths).

For the **Rejected** branch, add an **End Event** node labeled `endRejected`.

***

## Step 8: Add a business rule for risk scoring (optional)

You can add a **Business Rule Action** on the `receiveKycResult` node to enrich the KYC response with custom logic before the gateway evaluates it.

**Action type:** Business Rule
**Language:** JavaScript

```javascript theme={"system"}
// Normalize the KYC result for downstream processing
var status = input.kycResult.status;
var score = input.kycResult.score;

// Override status based on custom score thresholds
if (status === "REVIEW" && score >= 75) {
  output.put("kycResult.status", "PASSED");
} else if (status === "REVIEW" && score < 50) {
  output.put("kycResult.status", "FAILED");
}

// Flag high-risk countries for additional review
var highRiskCountries = ["XX", "YY", "ZZ"];
if (highRiskCountries.indexOf(input.address.country) !== -1 && status === "PASSED") {
  output.put("kycResult.status", "REVIEW");
  output.put("kycResult.reasons", ["High-risk jurisdiction flagged for manual review"]);
}
```

<Info>
  Business rules execute synchronously within the process engine. Use them for lightweight data transformations and decision logic. For details, see [Business Rule Action](../../docs/building-blocks/actions/business-rule-action/business-rule-action).
</Info>

***

## Step 9: Configure stages for Task Manager

Define [stages](../../docs/platform-deep-dive/core-extensions/task-management/using-stages) to track progress in the Task Manager:

| Stage name       | Assigned to nodes                                                 |
| ---------------- | ----------------------------------------------------------------- |
| Data Collection  | `personalInfo`, `addressInfo`, `employmentInfo`, `documentUpload` |
| KYC Verification | `sendKycRequest`, `receiveKycResult`                              |
| Manual Review    | `manualReview`                                                    |
| Completion       | `sendGenerateWelcomeLetter`, `sendEmailNotification`              |

Enable **Update Task Management** on the first user task node (`personalInfo`) and the manual review node (`manualReview`) so that process instances appear in the Task Manager with their current stage.

***

## Testing

<Steps>
  <Step title="Test the happy path (KYC passes)">
    Start a new process instance and fill in all four form steps with valid data. Use a national ID that your mock KYC service recognizes as valid.

    Verify:

    * The KYC integration workflow completes and returns `status: PASSED`
    * The welcome letter is generated (check the document storage)
    * The confirmation email is sent to the customer email address
    * The process ends at the success End Event

    ```json theme={"system"}
    {
      "customer": {
        "firstName": "Jane",
        "lastName": "Smith",
        "dateOfBirth": "1990-05-15",
        "nationalId": "AB1234567",
        "email": "jane.smith@example.com",
        "phone": "+44 7700 900000"
      },
      "address": {
        "street": "42 Oak Lane",
        "city": "London",
        "postalCode": "SW1A 1AA",
        "country": "GB"
      },
      "employment": {
        "status": "EMPLOYED",
        "employer": "Acme Corp",
        "monthlyIncome": 4500,
        "startDate": "2020-03-01"
      }
    }
    ```
  </Step>

  <Step title="Test the manual review path (KYC fails)">
    Start a new instance with data that triggers a `FAILED` or `REVIEW` KYC status.

    Verify:

    * The process routes to the `manualReview` user task
    * The task appears in the Task Manager for the BackOffice swimlane
    * Approving the review generates the welcome letter and sends the email
    * Rejecting the review ends the process at the rejection End Event
  </Step>

  <Step title="Test SLA escalation">
    Start a manual review scenario and let the 48-hour timer expire (for testing, temporarily change the duration to `PT1M` — one minute).

    Verify:

    * The escalation email is sent to the configured manager address
    * The review task remains active (non-interrupting timer)
    * The reviewer can still approve or reject after escalation
  </Step>

  <Step title="Test form navigation">
    Verify that the **Back** button on each form step returns the user to the previous step without losing entered data.

    Verify that required field validations prevent advancing to the next step when fields are empty.
  </Step>
</Steps>

***

## What you learned

In this tutorial, you built a complete customer onboarding process that demonstrates several core FlowX capabilities:

* **Multi-step forms** — using sequential User Task nodes with form components to collect structured data across multiple screens
* **Integration workflows** — delegating external API calls (KYC verification) to reusable integration workflows triggered via the Start Integration Workflow action
* **Conditional routing** — using Exclusive Gateway nodes with JavaScript conditions to branch process logic based on data values
* **Document generation** — using the Documents Plugin with Kafka Send/Receive Message Tasks to generate documents from HTML templates
* **Notifications** — using the Notifications Plugin to send email confirmations
* **Task assignment** — using swimlanes and the Task Management plugin to route manual review tasks to specific roles
* **SLA tracking** — using Timer Boundary Events to enforce and escalate overdue tasks
* **Business rules** — using JavaScript business rules to enrich and transform data within the process

***

## Next steps

<CardGroup>
  <Card title="Process definitions" icon="diagram-project" href="../../docs/building-blocks/process/process-definition">
    Deep-dive into process configuration options
  </Card>

  <Card title="Integration Designer" icon="plug" href="../../docs/platform-deep-dive/integrations/integration-designer">
    Build more integration workflows for external systems
  </Card>

  <Card title="Task Management" icon="list-check" href="../../docs/platform-deep-dive/core-extensions/task-management/task-management-overview">
    Configure task routing and assignment rules
  </Card>

  <Card title="Mortgage advisor chatbot" icon="building-columns" href="./mortgage-advisor">
    Build a conversational AI app as a companion to this BPMN tutorial
  </Card>
</CardGroup>


# Document processing pipeline
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/document-processing

Build an AI-powered document verification pipeline that classifies uploaded documents, extracts structured data, and reconciles it against application data.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

In this tutorial, you build a **document processing pipeline** that verifies customer onboarding documents against application data. The pipeline receives uploaded files (ID card, proof of address, salary slip), classifies each document, extracts structured data, compares it to what the applicant declared, and routes discrepancies to a human reviewer.

**What you will build:**

* A **file upload** UI that accepts multiple documents
* A **document classification** workflow that identifies each document type using AI
* A **fan-out extraction** pipeline that routes each type to a specialized extractor
* An **AI reconciliation** step that compares extracted data against application data
* **Business rules** that flag mismatches (name, address, income)
* A **human review** task for documents with discrepancies
* A **summary generation** step that produces a verification report

**AI node types used:** Text Understanding, Extract Data from File, Text Generation

**Patterns demonstrated:** [Fan-out extraction](../patterns/fan-out-extraction), [AI comparison and reconciliation](../patterns/ai-comparison-reconciliation)

***

## Architecture overview

The pipeline processes documents in four phases: upload, classify and extract, reconcile, and review.

```mermaid theme={"system"}
flowchart TD
    A["User uploads documents"] --> B["User Task<br/>(file upload UI)"]
    B --> C["Send / Receive Message Task"]
    C -. "Workflow: classifyAndExtract<br/>(per document)" .-> C
    C --> D["Send / Receive Message Task"]
    D -. "Workflow: reconcileData" .-> D
    D --> E["Business Rule<br/>(validation)"]
    E --> F{"Exclusive Gateway"}
    F -- "All valid" --> G["Auto-approve"]
    F -- "Exceptions found" --> H["Human Review Task"]
    G --> I["Send / Receive Message Task"]
    H --> I
    I -. "Workflow: generateSummary" .-> I
    I --> J(("End Event"))

    style A fill:#f0f4ff,stroke:#4a6fa5
    style J fill:#f0f4ff,stroke:#4a6fa5
```

**Workflow breakdown:**

| Workflow             | AI nodes                                    | Purpose                                                                 |
| -------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| `classifyAndExtract` | Text Understanding + Extract Data from File | Classify document type, then extract fields using type-specific prompts |
| `reconcileData`      | Text Understanding                          | Compare extracted fields against application data                       |
| `generateSummary`    | Text Generation                             | Produce a human-readable verification report                            |

***

## Prerequisites

Before starting, make sure you have:

* Access to a FlowX Designer workspace with AI Platform enabled
* Familiarity with creating processes, workflows, and UI flows in FlowX
* A project with the Documents Plugin configured (for file uploads)

***

## Data model

Define the following data model keys in your process. These keys hold the application data submitted by the customer and the results produced by the AI pipeline.

```json theme={"system"}
{
  "applicant": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "string",
    "address": {
      "street": "string",
      "city": "string",
      "postalCode": "string",
      "country": "string"
    },
    "monthlyIncome": "number",
    "employer": "string"
  },
  "documents": {
    "uploadedFiles": [
      {
        "fileId": "string",
        "filePath": "string",
        "fileName": "string"
      }
    ]
  },
  "extraction": {
    "classifiedDocs": [
      {
        "fileId": "string",
        "documentType": "string",
        "confidence": "number",
        "extractedData": "object"
      }
    ]
  },
  "reconciliation": {
    "matchRate": "number",
    "fieldResults": "array",
    "exceptions": "array",
    "overallStatus": "string"
  },
  "review": {
    "reviewerDecision": "string",
    "reviewerNotes": "string"
  },
  "summary": {
    "report": "string"
  }
}
```

<Tip>
  Define these keys under your process data model before building the workflows. The AI nodes and business rules reference these paths at runtime.
</Tip>

***

## Step 1: Build the classification and extraction workflow

Create a workflow named **`classifyAndExtract`**. This workflow receives a single document file path, classifies the document type, and then routes to the appropriate extraction branch.

This implements the [fan-out extraction pattern](../patterns/fan-out-extraction).

### 1.1 Add the classification node

Add a **Text Understanding** node as the first node after **Start Flow**. This node reads the document content and classifies it.

**Operation Prompt:**

```text theme={"system"}
You are a document classifier for a bank's customer onboarding process.
Analyze the provided document and determine its type.

Respond with exactly one of the following values:
- ID_CARD
- PROOF_OF_ADDRESS
- SALARY_SLIP
- UNKNOWN

Classification rules:
- ID_CARD: Government-issued identification documents (passport, national ID,
  driver's license). Contains photo, name, date of birth, document number.
- PROOF_OF_ADDRESS: Utility bills, bank statements, or government letters
  showing a name and residential address. Must be dated within the last
  3 months.
- SALARY_SLIP: Employment payslips or salary certificates showing employer
  name, employee name, gross/net salary, and pay period.
- UNKNOWN: Document does not match any of the above categories.

Base your classification on the document layout, headers, field labels,
and content structure. If uncertain, return UNKNOWN.
```

**Response schema:**

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "enum": ["ID_CARD", "PROOF_OF_ADDRESS", "SALARY_SLIP", "UNKNOWN"]
    },
    "confidence": {
      "type": "number",
      "description": "Classification confidence between 0 and 1"
    },
    "reasoning": {
      "type": "string",
      "description": "Brief explanation of why this type was chosen"
    }
  },
  "required": ["document_type", "confidence"]
}
```

**Response Key:** `classificationResult`

### 1.2 Add the Condition node

Add a **Condition** node after the Text Understanding node. Configure branches based on the `document_type` value:

| Branch      | Condition (Python)                                                     | Target                                    |
| ----------- | ---------------------------------------------------------------------- | ----------------------------------------- |
| **If**      | `input["classificationResult"]["document_type"] == "ID_CARD"`          | Extract Data from File (ID card)          |
| **Else if** | `input["classificationResult"]["document_type"] == "PROOF_OF_ADDRESS"` | Extract Data from File (proof of address) |
| **Else if** | `input["classificationResult"]["document_type"] == "SALARY_SLIP"`      | Extract Data from File (salary slip)      |
| **Else**    | *(default)*                                                            | Script node (unknown document)            |

<Info>
  The **Else** branch handles `UNKNOWN` documents. Use a Script node to return a structured error so the parent process can flag the document for manual classification.
</Info>

### 1.3 Configure type-specific extraction nodes

Each branch contains an **Extract Data from File** node with a prompt and schema tailored to that document type.

<Tabs>
  <Tab title="ID card">
    **Extraction Strategy:** LLM Model (handles varied ID layouts, photos, and security features)

    **Operation Prompt:**

    ```text theme={"system"}
    Extract all personal identification fields from this ID document.
    The document may be a passport, national ID card, or driver's license.
    If a field is not present or not legible, return null for that field.
    ```

    **Response schema:**

    ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "document_number": { "type": "string" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "date_of_birth": {
          "type": "string",
          "description": "Format: YYYY-MM-DD"
        },
        "nationality": { "type": "string" },
        "expiry_date": {
          "type": "string",
          "description": "Format: YYYY-MM-DD"
        },
        "issuing_authority": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "street": { "type": "string" },
            "city": { "type": "string" },
            "postal_code": { "type": "string" },
            "country": { "type": "string" }
          }
        }
      },
      "required": ["first_name", "last_name", "date_of_birth"]
    }
    ```

    **Response Key:** `extractedData`
  </Tab>

  <Tab title="Proof of address">
    **Extraction Strategy:** OCR Engine (utility bills and bank statements are typically clean scans)

    **Operation Prompt:**

    ```text theme={"system"}
    Extract the resident's name, full address, document date, and issuing
    organization from this proof of address document. The document may be a
    utility bill, bank statement, or government letter.
    If a field is not present, return null for that field.
    ```

    **Response schema:**

    ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "resident_name": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "street": { "type": "string" },
            "city": { "type": "string" },
            "postal_code": { "type": "string" },
            "country": { "type": "string" }
          }
        },
        "document_date": {
          "type": "string",
          "description": "Format: YYYY-MM-DD"
        },
        "issuing_organization": { "type": "string" },
        "document_type_detail": {
          "type": "string",
          "description": "e.g., electricity bill, water bill, bank statement"
        }
      },
      "required": ["resident_name", "address"]
    }
    ```

    **Response Key:** `extractedData`
  </Tab>

  <Tab title="Salary slip">
    **Extraction Strategy:** LLM Model (salary slips have complex tabular layouts with deductions)

    **Operation Prompt:**

    ```text theme={"system"}
    Extract salary and employment details from this payslip document.
    Capture the employee name, employer, pay period, and all salary
    components (gross, deductions, net).
    If a field is not present, return null for that field.
    ```

    **Response schema:**

    ```json theme={"system"}
    {
      "type": "object",
      "properties": {
        "employee_name": { "type": "string" },
        "employer_name": { "type": "string" },
        "pay_period": {
          "type": "string",
          "description": "e.g., January 2025, 2025-01"
        },
        "gross_salary": { "type": "number" },
        "net_salary": { "type": "number" },
        "deductions": {
          "type": "object",
          "properties": {
            "tax": { "type": "number" },
            "social_security": { "type": "number" },
            "health_insurance": { "type": "number" },
            "other": { "type": "number" }
          }
        },
        "currency": { "type": "string" },
        "employee_id": { "type": "string" }
      },
      "required": ["employee_name", "employer_name", "net_salary"]
    }
    ```

    **Response Key:** `extractedData`
  </Tab>
</Tabs>

<Warning>
  Choose the extraction strategy based on the document characteristics. LLM Model provides the highest accuracy for complex layouts but costs more per page. See [Extract Data from File](../agent-builder/extract-data-from-file) for strategy comparison.
</Warning>

### 1.4 Add the End Flow node

Add an **End Flow** node where all branches converge. Set the body to pass results back to the parent process:

```json theme={"system"}
{
  "output": {
    "documentType": "${classificationResult.document_type}",
    "confidence": "${classificationResult.confidence}",
    "extractedData": ${extractedData}
  }
}
```

***

## Step 2: Build the reconciliation workflow

Create a workflow named **`reconcileData`**. This workflow compares the extracted document data against the applicant's declared data.

This implements the [AI comparison and reconciliation pattern](../patterns/ai-comparison-reconciliation).

### 2.1 Add the comparison node

Add a **Text Understanding** node that receives both the extracted data and the application data.

**Operation Prompt:**

```text theme={"system"}
You are a document verification agent for a bank's customer onboarding
process. Compare the AI-extracted document data against the applicant's
declared data and produce a structured exception report.

Instructions:
1. Compare each field individually. Use fuzzy matching for names
   (e.g., "John Smith" vs "JOHN SMITH" is a MATCH, "Jon Smith" vs
   "John Smith" is a WARNING).
2. For addresses, compare at the component level (street, city,
   postal code). Minor formatting differences are acceptable.
3. For dates, normalize to YYYY-MM-DD before comparing.
4. For income, flag if the extracted net salary differs from the
   declared monthly income by more than 10%.
5. Compute an overall match rate as a percentage (0-100).
6. Assign a confidence score (0-100) reflecting how certain you are
   in the comparison results.
7. Flag each exception with a severity:
   - CRITICAL: Identity mismatch (different person), expired document
   - WARNING: Minor name variation, address component mismatch,
     income difference 10-25%
   - INFO: Formatting differences, abbreviations

Extracted document data:
${extraction.classifiedDocs}

Applicant's declared data:
${applicant}
```

**Response schema:**

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "matchRate": {
      "type": "number",
      "description": "Overall match rate from 0 to 100"
    },
    "confidenceScore": {
      "type": "number",
      "description": "Confidence in comparison accuracy from 0 to 100"
    },
    "fieldResults": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": { "type": "string" },
          "documentType": { "type": "string" },
          "extractedValue": { "type": "string" },
          "declaredValue": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["MATCH", "MISMATCH", "MISSING"]
          },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "WARNING", "INFO"]
          },
          "note": { "type": "string" }
        },
        "required": ["fieldName", "status", "severity"]
      }
    },
    "exceptions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": { "type": "string" },
          "description": { "type": "string" },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "WARNING", "INFO"]
          }
        },
        "required": ["fieldName", "description", "severity"]
      }
    },
    "overallStatus": {
      "type": "string",
      "enum": ["APPROVED", "REVIEW_REQUIRED", "REJECTED"],
      "description": "Recommended action based on match rate and exceptions"
    }
  },
  "required": ["matchRate", "confidenceScore", "fieldResults",
    "exceptions", "overallStatus"]
}
```

**Response Key:** `reconciliationResult`

### 2.2 Add the End Flow node

```json theme={"system"}
{
  "output": ${reconciliationResult}
}
```

***

## Step 3: Build the summary generation workflow

Create a workflow named **`generateSummary`** with a single **Text Generation** node.

**Operation Prompt:**

```text theme={"system"}
You are a compliance documentation assistant. Generate a document
verification summary report based on the reconciliation results.

Structure the report as follows:

1. VERIFICATION OVERVIEW
   - Applicant name
   - Number of documents processed
   - Overall match rate
   - Verification status (Approved / Review Required / Rejected)

2. DOCUMENT DETAILS
   For each document:
   - Document type and classification confidence
   - Fields extracted
   - Match/mismatch status per field

3. EXCEPTIONS
   - List all exceptions with severity and description
   - Highlight any CRITICAL issues

4. RECOMMENDATION
   - Clear recommendation based on the findings
   - Specific follow-up actions if needed

Use professional, concise language. Format the report in Markdown.

Applicant data:
${applicant}

Extraction results:
${extraction.classifiedDocs}

Reconciliation results:
${reconciliation}

Reviewer notes (if any):
${review.reviewerNotes}
```

**Response Key:** `summaryReport`

**End Flow body:**

```json theme={"system"}
{
  "output": {
    "report": "${summaryReport}"
  }
}
```

***

## Step 4: Build the BPMN process

Create a process named **`documentVerify`** that orchestrates the full pipeline using the workflows you built.

<Steps>
  <Step title="Add a User Task for file upload">
    Add a **User Task** node after the Start Event. This task presents the file upload UI to the user.

    Configure the task with:

    * **Task name:** `Upload documents`
    * **Assignment:** Assigned to the initiating user

    Attach a UI Flow (built in Step 5) that allows uploading multiple files.
  </Step>

  <Step title="Loop through uploaded documents">
    For each uploaded document, trigger the `classifyAndExtract` workflow. Add a **Send Message Task** node with a **Start Integration Workflow** action.

    **Input mapping:**

    ```json theme={"system"}
    {
      "filePath": "${documents.uploadedFiles[index].filePath}",
      "fileId": "${documents.uploadedFiles[index].fileId}"
    }
    ```

    Add a **Receive Message Task** node to capture the extraction output. Set the **Result Key** to `extraction.classifiedDocs[index]`.

    <Info>
      For multiple documents, repeat the Send/Receive pattern for each file, or use a loop structure with an exclusive gateway that iterates until all files are processed.
    </Info>
  </Step>

  <Step title="Trigger the reconciliation workflow">
    Add another **Send Message Task** with a **Start Integration Workflow** action pointing to the `reconcileData` workflow.

    **Input mapping:**

    ```json theme={"system"}
    {
      "classifiedDocs": "${extraction.classifiedDocs}",
      "applicant": "${applicant}"
    }
    ```

    Add a **Receive Message Task** node. Set the **Result Key** to `reconciliation`.
  </Step>

  <Step title="Add a business rule for validation">
    Add a **Business Rule** action (JavaScript) to perform deterministic validation checks that supplement the AI reconciliation.

    ```javascript theme={"system"}
    // Check if any CRITICAL exceptions exist
    var hasCritical = output.reconciliation.exceptions.some(function(e) {
      return e.severity === "CRITICAL";
    });

    // Check if ID document is expired
    var idDoc = output.extraction.classifiedDocs.find(function(d) {
      return d.documentType === "ID_CARD";
    });

    var isExpired = false;
    if (idDoc && idDoc.extractedData.expiry_date) {
      var expiryDate = new Date(idDoc.extractedData.expiry_date);
      isExpired = expiryDate < new Date();
    }

    // Check income discrepancy
    var salaryDoc = output.extraction.classifiedDocs.find(function(d) {
      return d.documentType === "SALARY_SLIP";
    });

    var incomeDiscrepancy = false;
    if (salaryDoc && salaryDoc.extractedData.net_salary) {
      var declared = output.applicant.monthlyIncome;
      var extracted = salaryDoc.extractedData.net_salary;
      var diff = Math.abs(declared - extracted) / declared;
      incomeDiscrepancy = diff > 0.1; // More than 10% difference
    }

    // Check all required document types are present
    var docTypes = output.extraction.classifiedDocs.map(function(d) {
      return d.documentType;
    });
    var missingId = docTypes.indexOf("ID_CARD") === -1;
    var missingAddress = docTypes.indexOf("PROOF_OF_ADDRESS") === -1;
    var missingSalary = docTypes.indexOf("SALARY_SLIP") === -1;

    // Set validation result
    output.validation = {
      hasCriticalExceptions: hasCritical,
      isIdExpired: isExpired,
      incomeDiscrepancy: incomeDiscrepancy,
      missingDocuments: {
        idCard: missingId,
        proofOfAddress: missingAddress,
        salarySlip: missingSalary
      },
      requiresReview: hasCritical || isExpired || incomeDiscrepancy
        || missingId || missingAddress || missingSalary
    };
    ```

    <Tip>
      Business rules provide deterministic, auditable checks. Use them alongside AI reconciliation to catch issues the LLM might miss, such as expired documents or missing required document types.
    </Tip>
  </Step>

  <Step title="Add the routing gateway">
    Add an **Exclusive Gateway** after the business rule. Configure two branches:

    | Branch       | Condition                                                                 | Target                        |
    | ------------ | ------------------------------------------------------------------------- | ----------------------------- |
    | Auto-approve | `validation.requiresReview == false` AND `reconciliation.matchRate >= 90` | Proceed to summary generation |
    | Human review | *(default)*                                                               | Human review User Task        |
  </Step>

  <Step title="Add the human review task">
    Add a **User Task** node for manual review. The reviewer sees:

    * Uploaded documents (viewable in a File Preview component)
    * Extracted data side-by-side with declared data
    * The exception report from reconciliation
    * Validation flags from the business rule

    The reviewer submits a decision:

    * **Approve** — continue to summary
    * **Reject** — end process with rejection status
    * **Request re-upload** — loop back to the upload step

    Store the decision in `review.reviewerDecision` and any notes in `review.reviewerNotes`.
  </Step>

  <Step title="Trigger the summary generation workflow">
    After both the auto-approve and human-review-approve paths converge, add a **Send Message Task** to trigger the `generateSummary` workflow.

    **Input mapping:**

    ```json theme={"system"}
    {
      "applicant": "${applicant}",
      "classifiedDocs": "${extraction.classifiedDocs}",
      "reconciliation": "${reconciliation}",
      "reviewerNotes": "${review.reviewerNotes}"
    }
    ```

    Add a **Receive Message Task**. Set the **Result Key** to `summary`.
  </Step>

  <Step title="Add the End Event">
    Add an **End Event** after the summary is received. The process instance now contains the full verification report at `summary.report`.
  </Step>
</Steps>

***

## Step 5: Build the upload UI

Create a **UI Flow** with a page for document upload.

<Steps>
  <Step title="Create the UI Flow">
    Go to **UI Flows** in the project sidebar and create a new UI Flow named `documentUpload`.
  </Step>

  <Step title="Add an upload component">
    Add a **File Upload** component to the page. Configure it to:

    * Accept multiple files
    * Restrict file types to PDF, JPG, PNG
    * Map uploaded file paths to `documents.uploadedFiles`
  </Step>

  <Step title="Add applicant data display">
    Add form fields (read-only) that display the applicant's declared data from `applicant`. This gives context to the person uploading documents.
  </Step>

  <Step title="Add a submit button">
    Add a **Button** component labeled **Submit documents**. Configure it to save the data and advance the User Task.
  </Step>
</Steps>

<Info>
  For the human review step, create a second UI Flow page that displays the extracted data, reconciliation results, and exception report alongside the original documents. Use a side-by-side layout so the reviewer can compare easily.
</Info>

***

## Step 6: Build the review UI

Create a second page in the UI Flow for the human review task.

The review page should include:

| Section               | Data source                   | Component                                            |
| --------------------- | ----------------------------- | ---------------------------------------------------- |
| Applicant info        | `applicant`                   | Read-only form fields                                |
| Uploaded documents    | `documents.uploadedFiles`     | File Preview                                         |
| Extraction results    | `extraction.classifiedDocs`   | Data table                                           |
| Reconciliation report | `reconciliation.fieldResults` | Data table with status badges                        |
| Exceptions            | `reconciliation.exceptions`   | List with severity highlighting                      |
| Validation flags      | `validation`                  | Alert components for each flag                       |
| Decision              | `review.reviewerDecision`     | Radio buttons (Approve / Reject / Request re-upload) |
| Notes                 | `review.reviewerNotes`        | Text area                                            |

<Tip>
  Use conditional visibility to highlight rows with `MISMATCH` or `CRITICAL` status in the reconciliation table. This draws the reviewer's attention to the issues that need their judgment.
</Tip>

***

## Testing

<Steps>
  <Step title="Test classification in isolation">
    Open the `classifyAndExtract` workflow and use **Run Workflow** with a test file. Upload sample documents one at a time and verify the classification output.

    | Test document        | Expected type      | Expected confidence |
    | -------------------- | ------------------ | ------------------- |
    | Scanned passport     | `ID_CARD`          | > 0.9               |
    | Electricity bill PDF | `PROOF_OF_ADDRESS` | > 0.9               |
    | Monthly payslip      | `SALARY_SLIP`      | > 0.9               |
    | Random brochure      | `UNKNOWN`          | \< 0.5              |
  </Step>

  <Step title="Test extraction accuracy">
    For each document type, compare the extracted fields against the actual document content. Check that:

    * Names are captured correctly (including accented characters)
    * Dates are in the expected `YYYY-MM-DD` format
    * Numeric values (salary, postal code) are accurate
    * Null is returned for missing fields (not hallucinated values)
  </Step>

  <Step title="Test reconciliation with known mismatches">
    Prepare test data with deliberate mismatches:

    ```json theme={"system"}
    {
      "applicant": {
        "firstName": "John",
        "lastName": "Smith",
        "monthlyIncome": 5000
      }
    }
    ```

    Upload an ID card with the name "Jonathan Smith" and a salary slip showing a net salary of 4200. Verify the reconciliation output flags:

    * Name variation as `WARNING`
    * Income discrepancy (16%) as `WARNING`
  </Step>

  <Step title="Test the business rule">
    Verify the JavaScript business rule catches:

    * Expired ID documents
    * Missing required document types
    * Income discrepancy above 10%
    * CRITICAL exceptions from reconciliation

    Test edge cases: all documents valid (auto-approve path), one missing document (review path), expired ID (review path).
  </Step>

  <Step title="Test the full end-to-end flow">
    Run the complete `documentVerify` process:

    1. Upload three documents (ID, proof of address, salary slip)
    2. Verify classification and extraction complete
    3. Check the reconciliation report
    4. If routed to review, complete the reviewer task
    5. Verify the summary report is generated

    Test both the auto-approve path (all documents match) and the human review path (with discrepancies).
  </Step>
</Steps>

***

## What you learned

In this tutorial, you built a document processing pipeline that demonstrates several key patterns:

* **Fan-out extraction** — classifying documents by type and routing each to a specialized extraction node with tailored prompts and schemas
* **AI reconciliation** — comparing AI-extracted data against application data with structured exception reports
* **Hybrid AI + business rules** — combining AI-driven comparison with deterministic validation (expired documents, missing types, income thresholds)
* **Human-in-the-loop** — routing edge cases to a reviewer while auto-approving clean results
* **Workflow composition** — building modular workflows for classification, reconciliation, and summary generation, then orchestrating them from a BPMN process

***

## Next steps

<CardGroup>
  <Card title="Fan-out extraction pattern" icon="arrows-split-up-and-left" href="../patterns/fan-out-extraction">
    Scale the classification and extraction pattern to dozens of document types
  </Card>

  <Card title="AI comparison and reconciliation" icon="code-compare" href="../patterns/ai-comparison-reconciliation">
    Deep-dive into the reconciliation pattern with threshold tuning
  </Card>

  <Card title="Extract Data from File" icon="file-lines" href="../agent-builder/extract-data-from-file">
    Configure extraction strategies, image extraction, and signature detection
  </Card>

  <Card title="AI node types" icon="diagram-project" href="../agent-builder/node-types">
    Reference for all AI node types available in Agent Builder
  </Card>
</CardGroup>


# Mortgage advisor chatbot
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/mortgage-advisor

Build a Chat Driven conversational AI mortgage advisor with built-in session memory, intent routing, a knowledge base, and hybrid AI + business rule recommendations.

<Warning>
  **Preview**

  Agent Builder is currently in preview and may change before general availability.
</Warning>

In this tutorial, you build a **mortgage advisor chatbot** — a Chat Driven conversational AI app that guides users through mortgage product selection. The app detects what the user wants, answers questions from a knowledge base, collects financial data across conversation turns, and generates personalized recommendations using a combination of AI and deterministic business rules.

**What you will build:**

* A **main Chat Driven workflow** that uses an **Intent Classification Agent** to route messages
* **Built-in session memory** that carries financial data across conversation turns
* A **knowledge base Q\&A** handler that answers mortgage questions from uploaded documents
* A **data collection** handler that extracts user financial data from free-text messages
* A **personalized offer** generator using hybrid AI extraction + business rule calculations
* A **small talk** responder and **fallback handler**

**AI node types used:** Intent Classification Agent, Text Generation, Custom Agent (with Knowledge Base and Send as Chat Reply)

**Patterns demonstrated:** [Intent classification](../patterns/intent-classification-routing), [Knowledge base RAG](../patterns/knowledge-base-rag), [Hybrid AI + business rules](../patterns/hybrid-ai-rules), [Session state management](../patterns/session-state-management)

***

## Architecture overview

The app is a **Chat Driven workflow** that uses an **Intent Classification Agent** to classify each user message and route it to the right handler. Each intent maps to a separate output branch on the node, eliminating the need for a Condition node. Each handler terminates in a Custom Agent node with **Send as Chat Reply** enabled, which delivers the response directly to the Chat component and updates session memory.

```mermaid theme={"system"}
flowchart TD
    A["Start<br/>(Chat Session ID, User Message)"] --> B["Intent Classification Agent"]
    B -- "Greetings" --> C["answerSmalltalk<br/>(Custom Agent → chat reply)"]
    B -- "Offer" --> D["answerPersonalisedOffer<br/>(Subworkflow: Hybrid AI + Rules → chat reply)"]
    B -- "Knowledge QA" --> E["knowledgeBaseQA<br/>(Custom Agent + KB → chat reply)"]
    B -- "Data Input" --> F["handleDataInput<br/>(Script → Custom Agent → chat reply)"]
    B -- "No Match" --> G["fallback<br/>(Custom Agent → chat reply)"]
    C --> H["End Flow"]
    D --> H
    E --> H
    F --> H
    G --> H
```

<Info>
  In Chat Driven workflows, responses are delivered to the user by Custom Agent nodes with **Send as Chat Reply** enabled, not by the End Flow node. The End Flow node has no body configuration.
</Info>

***

## Data model

In a Chat Driven workflow, the Start node provides **Chat Session ID**, **User Message**, and an optional **UI Flow Context** as dedicated input fields — you reference them as `${sessionId}`, `${userMessage}`, and `${context}` in downstream nodes. These are not keys you declare in the data model.

### mainChat data model

The mainChat workflow does not need any chat-specific keys in its data model — everything comes from the Start node fields and from handler subworkflow outputs.

### answerPersonalisedOffer data model

| Key                           | Type      | Description                                                         |
| ----------------------------- | --------- | ------------------------------------------------------------------- |
| `clientProfile`               | OBJECT    | Client financial data (extracted by AI from message)                |
| `clientProfile.age`           | NUMBER    | User age                                                            |
| `clientProfile.income`        | NUMBER    | Monthly income                                                      |
| `clientProfile.loan_amount`   | NUMBER    | Requested loan amount                                               |
| `clientProfile.loan_duration` | NUMBER    | Loan term in years                                                  |
| `filteredProducts`            | OBJECT    | Output from AI product filtering                                    |
| `calculationResults`          | OBJECT    | Output from business rule calculations (DTI, max loan, PMT)         |
| `rankedProducts`              | OBJECT\[] | Scored and ranked product recommendations                           |
| `reportText`                  | STRING    | Generated recommendation text consumed by the terminal Custom Agent |

<Info>
  **Built-in session memory**

  Chat Driven workflows retrieve the latest 3 message turns plus a summary of earlier exchanges automatically. Any Custom Agent node with **Use Memory** enabled receives this history as LLM context, so data mentioned in earlier turns (age, income, loan amount) is available to later turns without manual persistence. See [Session state management](../patterns/session-state-management) and [Conversational workflows — Session memory](../conversational-workflows#session-memory).
</Info>

***

## Prerequisites

Before starting, make sure you have:

* Access to a FlowX Designer workspace with AI Platform enabled
* Familiarity with creating workflows in FlowX
* A **Knowledge Base** data source with mortgage-related documents uploaded (see [Step 3](#step-3-build-the-knowledge-base-qa-handler))

***

## Step 1: Build the main orchestration workflow

Create a workflow named **`mainChat`** and select **Chat Driven** as the workflow type.

<Frame>
  ![Create workflow modal with Chat Driven selected as the workflow type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/mainChat_chat_driven_create.png)
</Frame>

<Warning>
  The workflow type cannot be changed after creation. Make sure you select **Chat Driven** — Output Focused workflows cannot be used from the Chat component.
</Warning>

### Review the Start node

The Start node is created automatically with three fields:

* **Chat Session ID** — a UUID populated by the Chat component at runtime (referenced as `${sessionId}`)
* **User Message** — the user's text message (referenced as `${userMessage}`)
* **UI Flow Context** — optional JSON object passed from the UI (referenced as `${context}`)

No Start body configuration is needed in Chat Driven workflows.

### Add the Intent Classification Agent

From the node palette, drag an **Intent Classification Agent** node (under **AI Agents**) onto the canvas and connect it to the **Start** node.

Configure the node:

**User Message:** `${userMessage}`

**Intents:**

| # | Label         | What it covers                                                                                                     |
| - | ------------- | ------------------------------------------------------------------------------------------------------------------ |
| 1 | `Greetings`   | Greetings and small talk                                                                                           |
| 2 | `Offer`       | The user asks for a product recommendation, a mortgage offer, product suggestions, or asks what mortgage fits them |
| 3 | `KB question` | Knowledge base questions about mortgage products or policies                                                       |
| 4 | `Data Input`  | User providing or updating personal data like income, age, or loan details                                         |

<Tip>
  Intent labels are read by the classifier LLM as guidance — richer phrasing reduces misclassifications. If a plain label like `Offer` routes user phrases like "Give me recommendations" to the wrong branch, broaden the text to cover more phrasings (as shown above). Turn on **Include Reason for Selection** while tuning to see the classifier's rationale for each decision.
</Tip>

**Response Key:** `intentResult`

The **If No Intent Matches** branch is a default output port that fires when the classifier can't confidently match any intent. It's always present on the node — you just need to connect it to the fallback handler in Step 2.

<Frame>
  ![Intent Classification Agent node showing intents list with the If No Intent Matches default branch](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/if_no_intent_matches.png)
</Frame>

**Use Memory:** OFF for this tutorial. The Intent Classification Agent also supports the **Use Memory** toggle — leave it OFF if each user message should be classified on its own. Turn it ON only if you want the classifier to resolve ambiguous follow-ups ("yes", "the first one", "tell me more") against prior conversation turns.

<Frame>
  ![Use Memory toggle on the Intent Classification Agent](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/use_memory.png)
</Frame>

<Tip>
  Toggle **Include Reason for Selection** ON while tuning intent labels. When enabled, the agent includes a rationale explaining why it chose each intent in its response — useful for diagnosing misclassifications. Turn it off once the intents are stable.
</Tip>

<Info>
  Each intent creates a separate output port on the node. When the agent classifies a message, the workflow continues along the matching branch — no Condition node needed.
</Info>

### Connect handler nodes to each branch

Add the following nodes and connect each to its corresponding intent output:

| Intent branch               | Handler node              | Type                                                        |
| --------------------------- | ------------------------- | ----------------------------------------------------------- |
| **Intent 1** (Greetings)    | `answerSmalltalk`         | Custom Agent (inline, Send as Chat Reply)                   |
| **Intent 2** (Offer)        | `answerPersonalisedOffer` | Subworkflow with terminal Custom Agent (Send as Chat Reply) |
| **Intent 3** (Knowledge QA) | `knowledgeBaseQA`         | Custom Agent (inline, Knowledge Base + Send as Chat Reply)  |
| **Intent 4** (Data Input)   | `handleDataInput`         | Script node → Custom Agent (Send as Chat Reply)             |
| **No Match**                | `fallback`                | Custom Agent (inline, Send as Chat Reply)                   |

<Info>
  Each branch delivers its response directly via a Custom Agent node with **Send as Chat Reply** enabled. No response-normalizer script is needed — the Chat component receives each reply as Markdown and persists it to session memory automatically.
</Info>

### Add the End Flow node

Add an **End Flow** node from the palette (it is not auto-created for Chat Driven workflows) and connect every handler branch to it. The End Flow node has no body configuration — responses are already delivered by the Custom Agent nodes upstream.

***

## Step 2: Build the inline handlers

The Greetings and No Match branches are handled by **Custom Agent** nodes placed directly in the `mainChat` workflow — no subworkflow needed.

<Info>
  **Shared Custom Agent settings for this tutorial**

  Every Custom Agent in `mainChat` uses the same two defaults:

  * **Use only prompt references as context:** ON — keeps each call scoped to the values referenced with `${...}` and reduces token usage. See [Custom Agent node](../conversational-workflows#use-only-prompt-references-as-context) for details.
  * **Include Task for Prompt Suggestions:** OFF — turn ON only if you want AI-generated follow-up prompts shown in the Chat component (5.7.0+). See [Custom Agent node](../conversational-workflows#include-task-for-prompt-suggestions).

  Only the **Use Memory** and **Send as Chat Reply** toggles vary per handler, so those are called out on each node below.
</Info>

### answerSmalltalk (Custom Agent)

Add a **Custom Agent** node named `answerSmalltalk` to the Greetings branch.

**Operation Prompt:**

```text theme={"system"}
Role: You are a friendly and professional Mortgage Assistant. Your goal
is to respond to greetings or casual conversation in a warm, trustworthy
manner, and subtly steer the conversation back toward the user's
mortgage goals.

User message: ${userMessage}

Response Guidelines:
- Tone: Warm, professional, and pragmatic.
- Acknowledge & Validate: Respond directly to what the user said.
- Subtle Pivot: End your response with a gentle nudge toward the
  mortgage process, without being pushy.
- Constraint: Keep the response under 3 sentences.
```

**Use Memory:** ON — lets the agent see the last few turns so it can tie small talk back to anything the user already shared.

**Send as Chat Reply:** ON — sends the response to the Chat component as Markdown and hides the Response Schema field.

<Info>
  With **Use Memory** enabled, you do not need to interpolate conversation history into the prompt manually. FlowX retrieves the latest 3 user/agent turns plus a summary and attaches them to the LLM call automatically.
</Info>

### fallback (Custom Agent)

Add a **Custom Agent** node named `fallback` on the No Match branch.

**Operation Prompt:**

```text theme={"system"}
Role: You are a mortgage assistant. The user sent a message that did not
match any known intent (greetings, product offer, knowledge base
question, or data input).

User message: ${userMessage}

Respond with a short, friendly message that acknowledges you did not
understand and offers three concrete options the user can try: asking a
mortgage question, sharing their financial details, or requesting a
product recommendation. Keep it under 3 sentences.
```

**Use Memory:** OFF — the fallback response is self-contained.

**Send as Chat Reply:** ON.

***

## Step 3: Build the data input handler

The Intent 4 branch combines a **Script** node (for deterministic data extraction) followed by a **Custom Agent** node (to confirm what was captured and send the chat reply). Script nodes cannot send chat replies on their own — only Custom Agent nodes can.

### 3a: handleDataInput Script

Add a **Script** node named `handleDataInput` on the Intent 4 branch. Since the Intent Classification Agent already routed the message here, the script can assume the user is providing personal data and uses simple string matching to extract values.

<Info>
  The FlowX script runtime uses a subset of Python. Avoid `enumerate()`, `.get()` with defaults, and `import` statements — use basic loops and `in` checks instead.
</Info>

**Script node (Python):**

```python theme={"system"}
message = ""
if "userMessage" in input:
    message = input["userMessage"]
clientProfile = {}
if "clientProfile" in input:
    clientProfile = input["clientProfile"]
words = message.lower().split()
cleanWords = []
for w in words:
    cleaned = ""
    for ch in w:
        if ch.isalnum():
            cleaned = cleaned + ch
    cleanWords.append(cleaned)
words = cleanWords
numWords = len(words)
i = 0
while i < numWords:
    word = words[i]
    if word in ["years", "year"] and i > 0:
        prev = words[i - 1]
        if prev.isdigit():
            val = int(prev)
            if i < numWords - 1 and words[i + 1] == "old":
                if val > 15 and val < 120:
                    clientProfile["age"] = val
            else:
                if val >= 1 and val <= 50:
                    clientProfile["loan_duration"] = val
    if word == "age" and i < numWords - 1:
        nxt = words[i + 1]
        if nxt.isdigit() and int(nxt) > 15 and int(nxt) < 120:
            clientProfile["age"] = int(nxt)
    i = i + 1
i = 0
while i < numWords:
    word = words[i]
    if word in ["income", "salary", "earn", "earning", "make"]:
        j = i + 1
        while j < numWords and j < i + 4:
            val = words[j]
            if val.isdigit() and int(val) > 100:
                clientProfile["income"] = int(val)
            j = j + 1
    i = i + 1
i = 0
while i < numWords:
    word = words[i]
    if word in ["loan", "borrow", "mortgage"]:
        j = i + 1
        while j < numWords and j < i + 5:
            val = words[j]
            if val.isdigit() and int(val) > 1000:
                clientProfile["loan_amount"] = int(val)
            j = j + 1
    i = i + 1
collected = []
keys = list(clientProfile.keys())
k = 0
while k < len(keys):
    key = keys[k]
    collected.append(str(key) + ": " + str(clientProfile[key]))
    k = k + 1
confirmationText = ""
if len(collected) > 0:
    confirmationText = "Got it! I have recorded: " + ", ".join(collected) + ". What else can I help you with?"
else:
    confirmationText = "I could not extract data. Please tell me your age, income, loan amount, or loan duration."
output["confirmationText"] = confirmationText
output["clientProfile"] = clientProfile
```

<Frame>
  ![handleDataInput Script node in the mainChat workflow with the Python data-extraction script](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/handleDataInput.png)
</Frame>

<Info>
  The age/duration disambiguation checks whether the word after a number + "years" is "old". For example, "30 years old" sets `age = 30`, while "25 years" sets `loan_duration = 25`.
</Info>

### 3b: Confirmation Custom Agent

Add a **Custom Agent** node after `handleDataInput` to deliver the confirmation as a chat reply.

**Operation Prompt:**

```text theme={"system"}
Role: You are a mortgage assistant confirming data you captured from the
user.

User message: ${userMessage}
System-prepared confirmation: ${confirmationText}

Return the system-prepared confirmation verbatim, or rephrase it in a
friendly tone if helpful. Do not invent any new numbers — only use what
is in the confirmation.
```

**Use Memory:** OFF — the Script already captured everything it needed from the current message.

**Send as Chat Reply:** ON.

<Tip>
  This two-node handler keeps extraction deterministic (Script) while letting the LLM phrase the response naturally (Custom Agent). You could also send `${confirmationText}` verbatim from a simpler Custom Agent without an LLM rewrite — trade off naturalness against token cost.
</Tip>

***

## Step 4: Build the knowledge base Q\&A handler

The Knowledge QA branch is a single **Custom Agent** node placed inline in the `mainChat` workflow (on the Intent 3 branch) with a Knowledge Base attached and **Send as Chat Reply** enabled.

### Set up the Knowledge Base

<Steps>
  <Step title="Create a Knowledge Base data source">
    In the **Integration Designer**, add a new **Knowledge Base** data source. Name it something descriptive like `MortgageKnowledgeBase`.
  </Step>

  <Step title="Upload mortgage documents">
    Upload PDF documents covering:

    * Mortgage product sheets (rates, terms, eligibility criteria)
    * FAQ documents (common questions about mortgages, DTI, LTV)
    * Regulatory guides (required documents, application process)

    Wait for automatic chunking and vector indexing to complete.
  </Step>

  <Step title="Test queries">
    Use the Knowledge Base test interface to verify that queries like "What is DTI?" and "What documents do I need?" return relevant chunks.
  </Step>
</Steps>

<Info>
  For detailed Knowledge Base setup, see the [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview) documentation.
</Info>

### Configure the Custom Agent node

Add a **Custom Agent** node named `knowledgeBaseQA` on the Intent 3 branch. Enable the **Knowledge Base** setting and select your `MortgageKnowledgeBase` data source.

**Retrieval parameters:**

| Parameter                  | Value                          |
| -------------------------- | ------------------------------ |
| **Max. Number of Results** | `4`                            |
| **Min. Relevance Score**   | `50`                           |
| **Metadata Filters**       | No filters (search all stores) |
| **Search Type**            | `hybrid` (5.7.0+)              |
| **Re-rank**                | ON (5.7.0+)                    |

**System Prompt:**

```text theme={"system"}
Role: You are a Mortgage Knowledge Base Expert who uses an integrated
Knowledge Base to provide accurate, data-grounded answers.

User question: ${userMessage}

Operating Procedure:
1. Query Analysis: Identify key terms from the user's question.
2. Knowledge Base Search: Find the most relevant document fragments.
3. Response Synthesis: Formulate a clear answer using ONLY the
   information found.

Strict Rules:
- If the information is not in the Knowledge Base, respond:
  "Our current knowledge base does not contain specific information
  about this topic."
- Reference the source document when possible.
- Never fabricate rates, terms, or requirements.
- Keep responses concise (under 200 words).
```

**Use Memory:** ON — so the agent can resolve follow-ups like "what about the second one?" against the previous answer.

**Send as Chat Reply:** ON.

<Warning>
  Without explicit grounding rules in the prompt, the LLM may fall back to its general training data and produce inaccurate mortgage information. Always include the "ONLY from knowledge base" instruction.
</Warning>

For more details on this pattern, see [Knowledge base RAG](../patterns/knowledge-base-rag).

***

## Step 5: Build the personalized offer handler

This is the most complex handler. It implements the [Hybrid AI + business rules](../patterns/hybrid-ai-rules) pattern — alternating between AI nodes and deterministic Script nodes. Because this branch benefits from structured intermediate data (calculation results, ranked products) that the other branches do not need, implement it as an **Output Focused subworkflow** called from `mainChat`, which returns a `reportText` string.

<Warning>
  **Send as Chat Reply and Use Memory are Chat Driven only.** Custom Agent nodes inside an Output Focused workflow do not expose those toggles — you cannot deliver a chat reply from inside a subworkflow. Instead, the subworkflow returns `reportText` via End Flow, and a separate Custom Agent in `mainChat` (on the Offer branch, after the Subworkflow node) handles the chat reply.
</Warning>

Create a workflow named **`answerPersonalisedOffer`** with **Output Focused** as the workflow type.

<Frame>
  ![answerPersonalisedOffer subworkflow showing Start, Text Understanding, financialCalculations Script, scoringRanking Script, and End Flow nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/answer_offer.png)
</Frame>

```text theme={"system"}
answerPersonalisedOffer (Output Focused):
  Start
    → Text Understanding (extract client data + filter products)
      → Script (financial calculations: PMT, DTI, max loan)
        → Script (score, rank, and format report)
          → End Flow (outputs reportText)

mainChat (Chat Driven), Offer branch:
  Intent Classification Agent → Offer output
    → Subworkflow (calls answerPersonalisedOffer, Response Key: offerOutput)
      → Custom Agent (Send as Chat Reply ON, reads ${offerOutput.reportText})
        → End Flow
```

In `mainChat`, connect a **Subworkflow** node on the Intent 2 branch that calls `answerPersonalisedOffer`, with Response Key `offerOutput`. Pass `${userMessage}` as the `userMessage` input. Then add a **Custom Agent** after the Subworkflow node to deliver the chat reply — see Step 5e below.

### Step 5a: AI understanding (extract and filter)

Add a **Text Understanding** node that extracts the client's financial profile from their message and filters the product catalog.

**Operation Prompt:**

```text theme={"system"}
You are a mortgage product filter. Extract the client's financial
details from their message and evaluate available products.

Client message: ${userMessage}

Available products:
1. fixed30 (Alpha Bank): 4.5% fixed, 30 years, min income 3000 EUR,
   max LTV 80%, min age 21, max age at maturity 70, prepayment after
   5 years, 20% down payment
2. variable20 (Beta Bank): 3.5% variable (EURIBOR 6M + 1.8%), 20 years,
   min income 2500 EUR, max LTV 85%, min age 23, max age at maturity 65,
   no prepayment first 3 years, 15% down payment
3. fixed15 (Gamma Bank): 4.0% fixed, 15 years, min income 4000 EUR,
   max LTV 75%, min age 25, max age at maturity 60, prepayment anytime,
   25% down payment

First extract from the message:
- age (number)
- monthly_income (number)
- loan_amount (number)
- loan_duration (number, in years)

Then for each product, evaluate eligibility and return JSON only:
{
  "client": {"age": 0, "monthly_income": 0, "loan_amount": 0,
             "loan_duration": 0},
  "filtered_products": [
    {"product_id": "fixed30", "qualitative_match_score": 0.8,
     "match_reasons": "brief explanation", "disqualified": false}
  ]
}

Only include products where disqualified is false. Return ONLY valid
JSON, no other text.
```

**Response Schema:**

```json theme={"system"}
{
  "type": "object",
  "properties": {
    "client": {
      "type": "object",
      "properties": {
        "age": { "type": "number" },
        "monthly_income": { "type": "number" },
        "loan_amount": { "type": "number" },
        "loan_duration": { "type": "number" }
      }
    },
    "filtered_products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": { "type": "string" },
          "qualitative_match_score": { "type": "number" },
          "match_reasons": { "type": "string" },
          "disqualified": { "type": "boolean" }
        }
      }
    }
  }
}
```

**Response Key:** `filteredProducts`

### Step 5b: Business rules (financial calculations)

Add a **Script** node (JavaScript) for deterministic financial calculations. These must be auditable and reproducible.

<Warning>
  AI node output in Script nodes arrives as **Java HashMaps**, not JavaScript objects. Use `.get("key")` to access properties and `.size()` / `.get(index)` for lists. Standard JavaScript methods like `Object.keys()` and `JSON.stringify()` do not work on these objects.
</Warning>

```javascript theme={"system"}
var fp = input.filteredProducts;
var client = fp.get("client");

var income = parseFloat(client.get("monthly_income")) || 0;
var loanAmount = parseFloat(client.get("loan_amount")) || 0;
var loanDuration = parseInt(client.get("loan_duration")) || 20;
var termMonths = loanDuration * 12;

function computePMT(principal, annualRate, months) {
  var r = annualRate / 12;
  if (r === 0) return principal / months;
  return principal * (r * Math.pow(1 + r, months)) /
          (Math.pow(1 + r, months) - 1);
}

var estimatedRate = 0.045;
var monthlyPayment = income > 0
  ? computePMT(loanAmount, estimatedRate, termMonths) : 0;
var dti = income > 0 ? monthlyPayment / income : 1;

var maxDtiShare = 0.43;
var allowablePayment = maxDtiShare * income;
var maxLoan = allowablePayment > 0
  ? allowablePayment * ((Math.pow(1 + estimatedRate / 12, termMonths) - 1) /
    (estimatedRate / 12 * Math.pow(1 + estimatedRate / 12, termMonths)))
  : 0;

output.calculationResults = {
  monthlyPayment: Math.round(monthlyPayment * 100) / 100,
  dti: Math.round(dti * 10000) / 10000,
  maxLoanAmount: Math.round(maxLoan),
  meetsEligibility: dti <= maxDtiShare,
  requestedVsMax: loanAmount <= maxLoan ? "within_limits" : "exceeds_limits"
};
```

<Info>
  The alternating AI-then-rules structure creates a natural audit trail. For any final recommendation, you can trace exactly which AI filtered the products and which formula computed the financial results.
</Info>

### Step 5c: Business rules (scoring, ranking, and report)

Add a second **Script** node (JavaScript) that scores products, ranks them, and generates the recommendation report text. The script writes the report to `reportText`, which the terminal Custom Agent node reads.

```javascript theme={"system"}
var calcResults = input.calculationResults || {};

var catalog = [
  {id: "fixed30", bankName: "Alpha Bank", rate: 0.045,
   allowsPrepayment: true, flexibleTerm: false, term: 30},
  {id: "variable20", bankName: "Beta Bank", rate: 0.035,
   allowsPrepayment: false, flexibleTerm: true, term: 20},
  {id: "fixed15", bankName: "Gamma Bank", rate: 0.04,
   allowsPrepayment: true, flexibleTerm: true, term: 15}
];

var fp = input.filteredProducts;
var aiProducts = fp.get("filtered_products");
var aiFiltered = [];
for (var i = 0; i < aiProducts.size(); i++) {
  var p = aiProducts.get(i);
  aiFiltered.push({
    product_id: "" + p.get("product_id"),
    qualitative_match_score:
      parseFloat(p.get("qualitative_match_score")) || 0.7,
    match_reasons: "" + p.get("match_reasons")
  });
}

var WEIGHT_RATE = 0.35;
var WEIGHT_QUALITATIVE = 0.25;
var WEIGHT_LTV = 0.20;
var WEIGHT_FLEXIBILITY = 0.20;

var scored = [];
for (var i = 0; i < aiFiltered.length; i++) {
  var product = aiFiltered[i];
  var details = null;
  for (var j = 0; j < catalog.length; j++) {
    if (catalog[j].id === product.product_id) {
      details = catalog[j];
      break;
    }
  }
  if (!details) continue;
  var rateScore = 1 - (details.rate / 0.10);
  var flexScore = (details.allowsPrepayment ? 0.5 : 0) +
                  (details.flexibleTerm ? 0.5 : 0);
  var totalScore = (rateScore * WEIGHT_RATE) +
    (product.qualitative_match_score * WEIGHT_QUALITATIVE) +
    (0.8 * WEIGHT_LTV) +
    (flexScore * WEIGHT_FLEXIBILITY);
  scored.push({
    productId: product.product_id,
    bankName: details.bankName,
    rate: details.rate,
    term: details.term,
    totalScore: Math.round(totalScore * 1000) / 1000,
    matchReasons: product.match_reasons
  });
}

scored.sort(function(a, b) { return b.totalScore - a.totalScore; });
var top = scored.slice(0, 3);

var mp = calcResults.monthlyPayment || 0;
var dti = calcResults.dti || 0;
var maxLoan = calcResults.maxLoanAmount || 0;
var eligible = calcResults.meetsEligibility !== false;

var report = "Mortgage Recommendation Report. ";
report += "Eligibility Assessment: ";
report += "Estimated monthly payment: " + mp + " EUR. ";
report += "Debt-to-income ratio: " + (dti * 100).toFixed(1) + "%. ";
report += "Maximum eligible loan: " + maxLoan + " EUR. ";
report += "Status: " + (eligible ? "Eligible" : "May need adjustment")
  + ". ";
report += "Top Recommendations: ";

for (var k = 0; k < top.length; k++) {
  var p = top[k];
  report += (k + 1) + ". " + p.bankName + " (" + p.productId + ") - "
    + (p.rate * 100) + "% for " + p.term + " years. ";
  report += "Score: " + p.totalScore + ". " + p.matchReasons + ". ";
}

report += "Next Steps: Compare the options above, gather required "
  + "documents, and schedule a consultation with your preferred bank.";

output.reportText = report;
output.rankedProducts = top;
```

<Info>
  The report is generated as plain text in the Script node rather than fully inside an LLM node. This keeps the numbers deterministic and auditable. The terminal Custom Agent (Step 5d) rephrases the report into a friendly chat reply.
</Info>

### Step 5d: End Flow (output the report)

Add an **End Flow** node after the scoring Script. Configure the End Flow body to expose `reportText` as a workflow output:

```json theme={"system"}
{
  "reportText": "${reportText}"
}
```

That's it for the subworkflow — save `answerPersonalisedOffer`.

### Step 5e: Terminal Custom Agent in mainChat (Send as Chat Reply)

Switch back to `mainChat`. On the Offer branch, after the Subworkflow node, add a **Custom Agent** node. This is where the chat reply is delivered.

**Operation Prompt:**

```text theme={"system"}
Role: You are a mortgage advisor presenting a personalized
recommendation to the client.

User message: ${userMessage}
System-prepared report: ${offerOutput.reportText}

Present the system-prepared report to the client in a warm,
professional tone. Preserve every number and product name exactly —
do not invent rates, terms, or eligibility details. Close with an
invitation to ask follow-up questions.
```

**Use only prompt references as context:** ON (default)

**Use Memory:** OFF — the report is fully self-contained.

**Send as Chat Reply:** ON.

**Include Task for Prompt Suggestions:** OFF.

Connect this Custom Agent to the **End Flow** node on `mainChat`.

<Warning>
  If you prefer zero LLM paraphrasing for compliance reasons, replace the Operation Prompt with `${offerOutput.reportText}` only and add an instruction: "Return the system-prepared report verbatim." The chat reply will then be the exact report string.
</Warning>

***

## Step 6: Connect to the chat UI

You have two options for wiring `mainChat` to a UI. Pick one.

### Option A: Chat-Based UI Flow (recommended, 5.7.0+)

<Frame>
  ![Chat-Based UI Flow hosting the mortgage advisor Chat component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_ui_flow.png)
</Frame>

<Steps>
  <Step title="Create a Chat-Based UI Flow">
    Go to **UI Flows** and create a new UI Flow, selecting **Chat-Based** as the experience type. Set `mainChat` as the default conversational workflow.

    <Frame>
      ![Create UI Flow modal with Chat-Based selected as the experience type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_chat_based.png)
    </Frame>
  </Step>

  <Step title="Add a Chat component">
    Any Chat component added to this UI Flow uses `mainChat` by default — no per-component configuration needed.
  </Step>

  <Step title="Test the chat">
    Click **Run** to preview the UI Flow and interact with the chatbot.
  </Step>
</Steps>

### Option B: Chat component per UI Flow page

<Steps>
  <Step title="Create a UI Flow">
    Create a standard UI Flow (e.g., `chat`) and add a **Page**.
  </Step>

  <Step title="Add a Chat component">
    Drag a **Chat** component onto the page. In the component settings, set the **Workflow** property to `mainChat`.
  </Step>

  <Step title="Test the chat">
    Click **Run** to preview.
  </Step>
</Steps>

<Info>
  For details on configuring chat experiences with built-in session memory, see [Conversational workflows](../conversational-workflows). For the Chat component reference, see [Chat component](../chat-component).
</Info>

***

## Step 7 (optional): Share captured data across turns

By default, the `answerPersonalisedOffer` subworkflow re-extracts all financial data from the **current** user message — it does not see conversation memory (memory is a Chat Driven feature, and the subworkflow is Output Focused). This means users must provide age, income, loan amount, and duration in a single Offer request.

If you want the subworkflow to reuse data the user shared in earlier turns (captured by `handleDataInput`), pass `clientProfile` from `mainChat` into the subworkflow.

<Steps>
  <Step title="Declare clientProfile as an input on the subworkflow">
    In `answerPersonalisedOffer`, open the Data Model panel. Add `clientProfile` (OBJECT) if not already there, and toggle **Input Parameter** ON.
  </Step>

  <Step title="Map clientProfile on the Subworkflow node in mainChat">
    In `mainChat`, open the Subworkflow node on the Offer branch. Map the `clientProfile` input: `clientProfile ← ${clientProfile}`. The `clientProfile` key on the Chat Driven workflow is populated by `handleDataInput` on previous Data Input turns.

    <Warning>
      Chat Driven workflow data does not persist across workflow invocations — each new user message starts a fresh workflow. To carry `clientProfile` across turns, write it to a persistent store (e.g., a FlowX Database keyed by Chat Session ID) from `handleDataInput`, and read it back at the start of each `mainChat` invocation. See [Session state management](../patterns/session-state-management) for the pattern.
    </Warning>
  </Step>

  <Step title="Update the Text Understanding prompt to prefer existing data">
    In the subworkflow's Step 5a prompt, reference `${clientProfile}` as prior context. Modify the extraction instruction:

    ```text theme={"system"}
    Existing client profile (from earlier turns, may be empty):
    ${clientProfile}

    Client message: ${userMessage}

    Extract client data. Prefer values from the existing client profile
    over the current message when both are available. Only fall back to
    extracting from the current message for fields missing in the profile.
    ```
  </Step>

  <Step title="Update Script 5b to merge sources">
    In the financial-calculations script, fall back to `input.clientProfile` when the AI extraction didn't find a field. Example guard for income:

    ```javascript theme={"system"}
    var income = parseFloat(client.get("monthly_income")) || 0;
    if (income === 0 && input.clientProfile) {
      var cp = input.clientProfile;
      income = parseFloat(cp.get ? cp.get("income") : cp.income) || 0;
    }
    ```

    Apply the same fallback for `loanAmount` and `loanDuration`.
  </Step>
</Steps>

<Info>
  This extension trades simplicity for multi-turn robustness. The base tutorial keeps the subworkflow stateless on purpose — it's easier to reason about and easier to test in isolation. Add this extension only when your users consistently spread financial data across multiple turns.
</Info>

***

## Testing

<Steps>
  <Step title="Test the mainChat workflow directly">
    Open `mainChat` and click **Run Workflow**. In the test modal, provide:

    * **Chat Session ID** — any valid UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`). Reuse the same UUID across test runs to verify multi-turn memory.
    * **User Message** — the message to test (e.g., `What is a debt-to-income ratio?`).

    <Warning>
      The Chat Session ID must be a valid UUID. A plain string like `test-session-1` causes a runtime error: `Invalid UUID string`.
    </Warning>
  </Step>

  <Step title="Test the full chat flow">
    Run the UI Flow that embeds the Chat component. With built-in session memory, financial details captured in earlier turns are available to later turns — the user can spread data across messages:

    | Turn | Message                                   | Expected behavior                                                                             |
    | ---- | ----------------------------------------- | --------------------------------------------------------------------------------------------- |
    | 1    | "Hi there!"                               | Greeting response, nudge toward mortgage                                                      |
    | 2    | "I am 30 years old and my income is 5000" | Acknowledges data (age, income recorded)                                                      |
    | 3    | "Loan of 200000 EUR for 25 years"         | Acknowledges additional data (loan\_amount, loan\_duration recorded)                          |
    | 4    | "Give me product recommendations."        | Recommendation report using data from turns 2 and 3 (memory makes the prior values available) |

    <Frame>
      ![Chat UI showing mortgage recommendation report with eligibility assessment and ranked product recommendations](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/mortgage_report_chat.png)
    </Frame>
  </Step>

  <Step title="Test edge cases">
    | Test message                           | Expected intent branch | Expected behavior               |
    | -------------------------------------- | ---------------------- | ------------------------------- |
    | "What documents do I need to apply?"   | Knowledge QA           | Answer from knowledge base      |
    | "asdfghjk"                             | No Match               | Fallback response               |
    | "I changed my mind, my income is 6000" | Data Input             | Updates income, confirms change |
  </Step>
</Steps>

***

## What you learned

In this tutorial, you built a full-featured Chat Driven app that demonstrates:

* **Chat Driven workflow basics** — dedicated Start node fields, `${userMessage}` interpolation, simplified End Flow ([guide](../conversational-workflows))
* **Built-in session memory** — multi-turn context without manually persisting conversation history
* **Intent classification and routing** — using an Intent Classification Agent to classify messages and route to handler branches automatically ([pattern](../patterns/intent-classification-routing))
* **Send as Chat Reply** — delivering responses to the Chat component directly from Custom Agent nodes
* **Knowledge base RAG with re-ranking** — grounding answers in uploaded documents using a Custom Agent with Knowledge Base, hybrid search, and re-rank ([pattern](../patterns/knowledge-base-rag))
* **Hybrid AI + business rules** — combining AI qualitative filtering with deterministic financial calculations for auditable recommendations ([pattern](../patterns/hybrid-ai-rules))

***

## Extending the chatbot

Once the base app works, these Chat Driven features can add polish and context-awareness:

* **[AI Triggers](../conversational-workflows#ai-triggers)** (5.7.0+) — let different UI Flow pages launch `mainChat` with parameterized starting messages, e.g., "Help me refinance order \$" from an account page
* **[Navigate in UI Flow node](../conversational-workflows#navigate-in-ui-flow-node)** — add an action branch that opens a mortgage application form with pre-filled data when the user accepts a recommendation
* **[Conversation Context](../conversational-workflows#setting-context-from-a-ui-flow)** (5.7.0+) — pass UI state (active customer ID, current page) to the workflow via the Start node's **UI Flow Context** field
* **[Knowledge Base metadata filters](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#user-defined-metadata)** — as the KB grows beyond a handful of documents, tag each store (e.g., `topic: basics | application | faq`) and pass metadata filters to the KB Q\&A Custom Agent to scope retrieval to the right subset. The 5.7.0 query builder supports typed operators and AND/OR grouping.

***

## Next steps

<CardGroup>
  <Card title="Conversational workflows" icon="comments" href="../conversational-workflows">
    Full reference for Chat Driven workflows, AI Triggers, and session memory
  </Card>

  <Card title="AI patterns" icon="puzzle-piece" href="../patterns/overview">
    Deep-dive into the patterns used in this tutorial
  </Card>

  <Card title="Node types reference" icon="diagram-project" href="../agent-builder/node-types">
    Detailed configuration reference for all AI node types
  </Card>

  <Card title="Knowledge Base integration" icon="database" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
    Create and manage Knowledge Bases for RAG
  </Card>
</CardGroup>


# Tutorials
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/overview

Step-by-step guides for building real-world AI apps with FlowX.AI, based on production-grade examples.

Learn how to build AI-powered apps on FlowX by following end-to-end tutorials based on real implementations.

## Available tutorials

<CardGroup>
  <Card title="Mortgage advisor chatbot" icon="building-columns" href="./mortgage-advisor">
    Build a Chat Driven conversational AI mortgage advisor that collects client data across turns, evaluates eligibility across multiple banks, and generates personalized product recommendations.

    **You will learn:** Chat Driven workflows, built-in session memory, intent routing, knowledge base RAG with re-ranking, hybrid AI + business rules, Send as Chat Reply, chat UI integration
  </Card>

  <Card title="Document processing pipeline" icon="file-check" href="./document-processing">
    Build an AI-powered document verification pipeline that classifies uploaded documents, extracts structured data, and reconciles it against application data.

    **You will learn:** fan-out extraction, document classification, AI reconciliation, business rules validation, human-in-the-loop review
  </Card>

  <Card title="Customer onboarding with KYC" icon="user-plus" href="./customer-onboarding">
    Build a multi-step customer onboarding process with identity verification, document generation, manual review routing, and email notifications.

    **You will learn:** multi-step forms, REST API integration via workflows, exclusive gateways, document generation, task assignment, timer events, notifications
  </Card>
</CardGroup>

***

## What makes these different

These tutorials are derived from **production apps**, not hypothetical examples. Each one:

* Uses **real workflow structures** exported from working FlowX projects
* Shows how to combine **multiple AI node types** (extraction, understanding, generation) in a single app
* Demonstrates **integration patterns** (REST APIs, databases, email triggers, chat UI)
* Includes the **business logic layer** — not just the AI parts

***

## Before you start

<Info>
  These tutorials assume familiarity with FlowX Designer basics — creating processes, workflows, data sources, and UI flows. If you are new to FlowX, start with the [FlowX Academy](https://academy.flowx.ai) courses first.
</Info>

Each tutorial is structured as:

1. **Architecture overview** — what you are building and how the pieces fit together
2. **Data model** — the data types and sources you need
3. **Workflows** — step-by-step workflow construction with AI nodes
4. **Process orchestration** — BPMN processes that tie workflows together
5. **UI** — the user-facing interface (chat or task management)
6. **Testing** — how to validate the end-to-end flow

***

## Related resources

<CardGroup>
  <Card title="AI patterns" icon="puzzle-piece" href="../patterns/overview">
    Reusable patterns extracted from these tutorials
  </Card>

  <Card title="Agent Builder" icon="robot" href="../agent-builder/overview">
    Node types and configuration reference
  </Card>

  <Card title="Node types" icon="diagram-project" href="../agent-builder/node-types">
    Detailed reference for each AI node type
  </Card>

  <Card title="Using agents" icon="play" href="../using-agents/overview">
    Integration options for deploying agents
  </Card>
</CardGroup>


# BPMN integration
Source: https://docs.flowx.ai/5.9/ai-platform/using-agents/bpmn-integration

Trigger AI agents from BPMN workflow nodes for automated document processing, decisions, and content generation.

Integrate AI agents directly into your BPMN processes to automate document processing, make intelligent decisions, and generate content without user interaction.

## Overview

BPMN integration allows you to:

* **Automate document processing** in the background
* **Make AI-powered decisions** at process gateways
* **Generate content** automatically within workflows
* **Validate data** using AI analysis

## Integration methods

### Method 1: Start Integration Workflow action

Use the **Start Integration Workflow** action to call an AI agent from any BPMN node.

<Steps>
  <Step title="Add a Service Task">
    Add a Service Task node to your process where you want to trigger the agent.
  </Step>

  <Step title="Configure the action">
    Add a **Start Integration Workflow** action and select your agent workflow.
  </Step>

  <Step title="Map input data">
    Configure which process data to send to the agent (documents, text, parameters).
  </Step>

  <Step title="Handle the response">
    Map the agent's response back to process variables.
  </Step>
</Steps>

<Card title="Start Integration Workflow" icon="play" href="/5.9/docs/building-blocks/actions/start-integration-workflow">
  Detailed configuration reference
</Card>

### Method 2: Custom Agent Node

For complex agent interactions, use the Custom Agent Node in Integration Designer:

| Feature              | Start Integration Workflow | Custom Agent Node       |
| -------------------- | -------------------------- | ----------------------- |
| **Setup complexity** | Simple                     | More complex            |
| **Flexibility**      | Standard call/response     | Full workflow control   |
| **Error handling**   | Basic                      | Advanced                |
| **Best for**         | Single agent calls         | Multi-step AI workflows |

<Card title="Custom Agent Node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
  Integration Designer agent configuration
</Card>

## Common patterns

### Document extraction

Extract data from uploaded documents and continue the process with structured data.

```
User uploads document → Service Task calls extraction agent →
Agent returns structured data → Process continues with data
```

**Configuration:**

* Input: Document file ID or content
* Output: Extracted fields mapped to process variables
* Error handling: Route to manual review if confidence is low

### Automated decisions

Use AI to make or recommend decisions at process gateways.

```
Process reaches gateway → Service Task calls decision agent →
Agent returns recommendation → Gateway routes based on result
```

**Configuration:**

* Input: All relevant process data
* Output: Decision result and confidence score
* Human override: Optional review step for low-confidence decisions

### Content generation

Generate documents, emails, or reports automatically.

```
Process collects data → Service Task calls generation agent →
Agent produces content → Content stored/sent
```

**Configuration:**

* Input: Template reference and data to include
* Output: Generated content (text, HTML, or document)
* Review: Optional human approval before sending

## Input/Output mapping

### Sending data to agents

Map process variables to agent input:

```javascript theme={"system"}
// Example input mapping
{
  "documentId": "${processInstanceData.uploadedDocument.fileId}",
  "applicantName": "${processInstanceData.application.fullName}",
  "extractionType": "loan_application"
}
```

### Receiving agent responses

Map agent output back to process variables:

```javascript theme={"system"}
// Example output mapping
{
  "extractedData": "processInstanceData.extraction",
  "confidence": "processInstanceData.extractionConfidence",
  "processingTime": "processInstanceData.agentMetrics.duration"
}
```

## Error handling

<AccordionGroup>
  <Accordion title="Timeout handling" icon="clock">
    Configure timeouts for agent calls. If an agent doesn't respond in time, route to a fallback path or retry.
  </Accordion>

  <Accordion title="Low confidence results" icon="question">
    Check confidence scores in gateway conditions. Route low-confidence results to human review.
  </Accordion>

  <Accordion title="Agent failures" icon="triangle-exclamation">
    Use boundary error events to catch agent failures and handle them gracefully.
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup>
  <Card title="Async processing" icon="clock">
    Use async patterns for long-running agent tasks to avoid blocking the process
  </Card>

  <Card title="Idempotency" icon="repeat">
    Design agent calls to be safe to retry in case of failures
  </Card>

  <Card title="Monitoring" icon="chart-line">
    Track agent call metrics (latency, success rate, confidence scores)
  </Card>

  <Card title="Fallbacks" icon="life-ring">
    Always have a fallback path for when agents fail or return uncertain results
  </Card>
</CardGroup>

## Related resources

<CardGroup>
  <Card title="Passing data between nodes" icon="arrow-right-arrow-left" href="/5.9/docs/building-blocks/process/passing-data-between-nodes">
    How node outputs land in process variables and how downstream nodes read them
  </Card>

  <Card title="Chat interface" icon="comments" href="./chat-interface">
    User-facing agent interaction
  </Card>

  <Card title="Integration Designer" icon="diagram-project" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Build complex integration workflows
  </Card>

  <Card title="Agent Builder" icon="robot" href="../agent-builder/overview">
    Create custom agents
  </Card>

  <Card title="Service Tasks" icon="gear" href="/5.9/docs/building-blocks/node/task-node">
    BPMN task configuration
  </Card>
</CardGroup>


# Chat interface
Source: https://docs.flowx.ai/5.9/ai-platform/using-agents/chat-interface

Add conversational AI to your applications with the FlowX.AI Chat component.

The Chat component provides a conversational interface for users to interact with AI agents. It supports real-time messaging, context-aware responses, and direct integration with your business processes.

## Overview

<CardGroup>
  <Card title="Real-time messaging" icon="bolt">
    Instant responses with streaming support
  </Card>

  <Card title="AI agent integration" icon="robot">
    Connect to custom agents or FlowX accelerators
  </Card>

  <Card title="Session management" icon="clock-rotate-left">
    Persistent conversations across sessions
  </Card>

  <Card title="Knowledge base access" icon="database">
    Context-aware responses from your data
  </Card>
</CardGroup>

## How it works

The Chat component follows a simple flow:

<Steps>
  <Step title="User initiates chat">
    User opens your application and the Chat component loads with a welcome message.
  </Step>

  <Step title="Message exchange">
    User sends a message. The component sends it to the configured AI agent workflow.
  </Step>

  <Step title="Agent processing">
    The agent processes the message, optionally querying knowledge bases or external systems.
  </Step>

  <Step title="Response delivery">
    The agent's response streams back to the user in real-time.
  </Step>
</Steps>

## Key concepts

### Agent workflows

The Chat component connects to an **agent workflow** that defines how messages are processed:

* **Input handling** - How user messages are received
* **AI processing** - Which models and prompts are used
* **Knowledge access** - What data sources the agent can query
* **Response generation** - How responses are formatted

### Session persistence

Conversations can be persisted to maintain context:

| Mode              | Description                            | Use case               |
| ----------------- | -------------------------------------- | ---------------------- |
| **Session-based** | Conversation lasts for browser session | Quick queries, support |
| **Persistent**    | Conversation saved to database         | Ongoing cases, history |

### Knowledge base integration

Agents can access knowledge bases for informed responses:

* **RAG (Retrieval-Augmented Generation)** - Agent searches relevant documents before responding
* **Semantic matching** - Finds conceptually similar content, not just keyword matches
* **Source attribution** - Responses can cite their sources

<Info>
  Knowledge base integration requires configuration in the agent workflow. See [Knowledge Base Overview](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview) for setup details.
</Info>

## Display modes

The Chat component supports different display modes:

| Mode           | Description                    |
| -------------- | ------------------------------ |
| **Standalone** | Full-page chat experience      |
| **Embedded**   | Chat panel within a larger UI  |
| **Floating**   | Expandable chat button overlay |

## Best practices

<AccordionGroup>
  <Accordion title="Set clear expectations" icon="comment">
    Use the welcome message to explain what the agent can help with. This reduces user frustration from mismatched expectations.
  </Accordion>

  <Accordion title="Provide context" icon="info">
    Pass relevant process data to the agent (user info, current step, etc.) so responses are contextually appropriate.
  </Accordion>

  <Accordion title="Handle limitations gracefully" icon="hand">
    Configure fallback responses for when the agent can't help. Offer escalation to human support when needed.
  </Accordion>

  <Accordion title="Design for mobile" icon="mobile">
    Test the chat experience on mobile devices. Ensure the interface works well with on-screen keyboards.
  </Accordion>
</AccordionGroup>

## Implementation

For detailed configuration and styling options, see the UI Designer documentation:

<Card title="Chat component configuration" icon="gear" href="/5.9/docs/building-blocks/ui-designer/ui-component-types/chat">
  Complete configuration reference for the Chat UI component
</Card>

## Related resources

<CardGroup>
  <Card title="BPMN integration" icon="diagram-project" href="./bpmn-integration">
    Trigger agents from workflows
  </Card>

  <Card title="Agent Builder" icon="robot" href="../agent-builder/overview">
    Create custom agents
  </Card>

  <Card title="Chat intents" icon="bullseye" href="../chat-intents">
    Configure intent-based routing
  </Card>

  <Card title="Knowledge bases" icon="database" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
    Connect your data sources
  </Card>

  <Card title="Conversational workflows" icon="messages" href="../conversational-workflows">
    Build multi-turn chat experiences with session memory
  </Card>
</CardGroup>


# Using AI agents
Source: https://docs.flowx.ai/5.9/ai-platform/using-agents/overview

Learn how to integrate and interact with AI agents in your FlowX.AI applications.

Once you've built or configured an AI agent, there are multiple ways to use it in your applications. This guide covers the different integration patterns available.

## Integration options

<CardGroup>
  <Card title="Chat interface" icon="comments" href="./chat-interface">
    Add conversational AI to your apps with the Chat component
  </Card>

  <Card title="BPMN integration" icon="diagram-project" href="./bpmn-integration">
    Trigger agents from workflow nodes
  </Card>

  <Card title="REST API" icon="code" href="/5.9/docs/api/process-api">
    Call agents programmatically via API
  </Card>

  <Card title="Custom Agent Node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
    Use agents within Integration Designer workflows
  </Card>
</CardGroup>

## Choosing an integration method

| Method                | Best for                                             | User interaction        |
| --------------------- | ---------------------------------------------------- | ----------------------- |
| **Chat interface**    | Conversational experiences, Q\&A, guided assistance  | Direct user interaction |
| **BPMN integration**  | Automated processing, document handling, decisions   | Background processing   |
| **REST API**          | External systems, custom frontends, batch processing | Programmatic access     |
| **Custom Agent Node** | Complex integrations, multi-step workflows           | Workflow orchestration  |

## Common patterns

### Pattern 1: Conversational assistant

Add a chat interface to help users complete complex tasks with AI guidance.

```
User opens app → Chat component loads → User asks questions →
Agent responds → User completes task with guidance
```

**Use cases:** Customer support, employee helpdesk, guided form completion

### Pattern 2: Document processing

Automatically process documents submitted through your application.

```
User uploads document → BPMN triggers agent → Agent extracts data →
Data validated → Process continues with extracted data
```

**Use cases:** Loan applications, claims processing, onboarding

### Pattern 3: Decision support

Provide AI-powered recommendations within business processes.

```
Process reaches decision point → Agent analyzes data →
Recommendation generated → Human reviews and approves/rejects
```

**Use cases:** Credit decisions, risk assessment, fraud detection

### Pattern 4: Content generation

Generate documents, reports, or communications automatically.

```
Process collects data → Agent generates content →
Content reviewed → Document sent/stored
```

**Use cases:** Reports, notifications, contracts, summaries

## Session management

AI agents maintain conversation context through sessions:

| Concept         | Description                                  |
| --------------- | -------------------------------------------- |
| **Session**     | A conversation thread between user and agent |
| **Context**     | Data and history available to the agent      |
| **Persistence** | Sessions can be saved and resumed            |
| **Isolation**   | Each user/process has separate sessions      |

<Info>
  Sessions are automatically managed when using the Chat component. For BPMN and API integrations, you control session lifecycle explicitly.
</Info>

## Data flow

When using agents, data flows through several stages:

<Steps>
  <Step title="Input preparation">
    User input, documents, or process data is formatted for the agent
  </Step>

  <Step title="Agent processing">
    The agent processes input using configured workflows and AI models
  </Step>

  <Step title="Response generation">
    Agent produces output: text, structured data, or actions
  </Step>

  <Step title="Result handling">
    Output is displayed to user, stored, or used to continue the process
  </Step>
</Steps>

## Knowledge bases

Agents can access knowledge bases for context-aware responses:

* **Custom knowledge bases** - Your uploaded documents and data
* **External sources** - Connected via MCP integrations

<Card title="Knowledge Base integration" icon="database" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
  Learn how to connect knowledge bases to your agents
</Card>

## Best practices

<AccordionGroup>
  <Accordion title="Start with clear use cases" icon="bullseye">
    Define specific tasks for your agent rather than general-purpose capabilities. Focused agents perform better.
  </Accordion>

  <Accordion title="Provide sufficient context" icon="info">
    Include relevant process data when calling agents. More context leads to better responses.
  </Accordion>

  <Accordion title="Handle errors gracefully" icon="triangle-exclamation">
    Always include fallback paths for when agents fail or return low-confidence results.
  </Accordion>

  <Accordion title="Monitor and iterate" icon="chart-line">
    Track agent performance and user feedback. Continuously improve prompts and workflows.
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup>
  <Card title="Chat interface" icon="comments" href="./chat-interface">
    Conversational AI integration
  </Card>

  <Card title="BPMN integration" icon="diagram-project" href="./bpmn-integration">
    Workflow-based agent usage
  </Card>

  <Card title="Agent Builder" icon="robot" href="../agent-builder/overview">
    Create custom agents
  </Card>

  <Card title="Config-time agents" icon="pencil-ruler" href="../pre-built-agents/overview">
    Design-time AI assistants
  </Card>
</CardGroup>


# Get build info by process instance
Source: https://docs.flowx.ai/5.9/docs/api/start-process/build-info-by-process-instance

GET {BASE_URL}/api/runtime/process-instance/{processInstanceUuid}/build/info
Retrieve the build associated with a running process instance, including the build settings used to render its UI.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

Returns the build that an already-started process instance is running on, with its associated build settings. Renderers call this when continuing a process across page refreshes; an external app would call it to discover the build version a process started against (for example, before fetching media files, substitution tags, or theme assets keyed by build).

The runtime resolves authorisation by checking that the process instance belongs to a workspace inside your organisation.

## Path parameters

<ParamField type="string">
  The UUID of the process instance.
</ParamField>

## Request headers

<ParamField type="string">
  Bearer token. Format: `Bearer <token>`.
</ParamField>

## Response

Returns a `BuildInfoDTO` with the build identifier, the workspace that owns it, and the build settings (theme, platforms, locale defaults, formatting).

```json theme={"system"}
{
  "workspaceId": "2ae77b6a-d284-4a0b-ab23-ceaa364c7122",
  "buildId": "7d5560be-3846-49fa-9c17-4059c54c7c5f",
  "applicationId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
  "buildSettings": {
    "applicationVersionId": "99f24e3f-e331-48ad-a503-2cc1cee5fb95",
    "platforms": "OMNICHANNEL",
    "themeId": "12345678-1234-1234-1234-123456789012",
    "defaultLanguageCode": "en"
  }
}
```

<RequestExample>
  ```bash theme={"system"}
  curl -X GET "{BASE_URL}/api/runtime/process-instance/{processInstanceUuid}/build/info" \
    -H "Authorization: Bearer <token>"
  ```
</RequestExample>


# Get build info by UI flow session
Source: https://docs.flowx.ai/5.9/docs/api/start-process/build-info-by-ui-flow-session

GET {BASE_URL}/api/runtime/ui-flow-session/{uiFlowSessionUuid}/build/info
Retrieve the build associated with a running UI flow session, including the build settings used to render it.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

Returns the build that an already-started UI flow session is running on, with its associated build settings. Renderers call this when continuing a UI flow across page refreshes; external callers can use it to discover the build version a session is bound to.

Authorisation is enforced by checking that the UI flow session's workspace belongs to your organisation.

## Path parameters

<ParamField type="string">
  The UUID of the UI flow session.
</ParamField>

## Request headers

<ParamField type="string">
  Bearer token. Format: `Bearer <token>`.
</ParamField>

## Response

Returns a `BuildInfoDTO` (same shape as [Get build info by process instance](./build-info-by-process-instance)).

<RequestExample>
  ```bash theme={"system"}
  curl -X GET "{BASE_URL}/api/runtime/ui-flow-session/{uiFlowSessionUuid}/build/info" \
    -H "Authorization: Bearer <token>"
  ```
</RequestExample>


# Start process by build id and process name
Source: https://docs.flowx.ai/5.9/docs/api/start-process/rest2

POST https://admin.devmain.flowxai.dev/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start
Start a FlowX process from your own app or backend by specifying the appId, buildId, and process definition name.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

## Base URL

* Always prepend the endpoint with the correct Base URL.
* For different environments (like staging or production), switch the base URL accordingly.

## Path Parameters

<Info>
  **Need help finding these IDs?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for detailed instructions on where to locate these values in FlowX Designer.
</Info>

<Warning>
  The pair (`buildId`, `appId`) must be valid and associated in the system. The `workspaceId` is internally resolved using the `buildId` from the build collection.
</Warning>

<ParamField type="string">
  The ID of the application. Must form a valid pair with the `buildId`.
</ParamField>

<ParamField type="string">
  The build ID for the runtime environment. Must form a valid pair with the `appId`.

  <Tip>
    When integrating from a frontend application or renderer, use the `buildId` value returned in the [build info response](./get-build-info).
  </Tip>
</ParamField>

<ParamField type="string">
  The name of the process definition to start.
</ParamField>

## Request headers

<ParamField type="string">
  Bearer token required for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField type="string">
  Indicates the media type of the request body. Must be set to `application/json`.
</ParamField>

<ParamField type="string">
  Identifies the client platform (e.g., `web`).
</ParamField>

<ParamField type="string">
  Specifies the media types that are acceptable for the response. Example: `application/json, text/plain, */*`.
</ParamField>

<ParamField type="string">
  Indicates supported content encoding algorithms for the response. Example: `gzip, deflate, br, zstd`.
</ParamField>

<ParamField type="string">
  Specifies language preferences for the response. Example: `en-GB,en-US;q=0.9,en;q=0.8`.
</ParamField>

<ParamField type="string">
  Identifies the client software making the request (e.g., browser or tool).
</ParamField>

<ParamField type="string">
  The address of the previous web page from which the request was made.
</ParamField>

## Request Body

This endpoint requires a JSON request body. The exact payload structure should conform to the process definition schema associated with `{processDefinitionName}`.

<ParamField type="string">
  Description of what key1 represents
</ParamField>

<ParamField type="string">
  Description of what key2 represents
</ParamField>

### Example Request Body

```json theme={"system"}
{
  "key1": "value1",
  "key2": "value2"
}
```

## Response

<ResponseField name="processDefinitionFlowxUuid" type="string">
  The unique identifier of the process definition within FlowX.
</ResponseField>

<ResponseField name="buildId" type="string">
  The ID of the build associated with the process.
</ResponseField>

<ResponseField name="buildStatusAtStart" type="string">
  The status of the build at the time the process was started (e.g., "COMMITTED").
</ResponseField>

<ResponseField name="applicationId" type="string">
  The ID of the application where the process was initiated.
</ResponseField>

<ResponseField name="parentApplicationId" type="string or null">
  The ID of the parent application if applicable, otherwise `null`.
</ResponseField>

<ResponseField name="rootApplicationId" type="string or null">
  The ID of the root application if applicable, otherwise `null`.
</ResponseField>

<ResponseField name="processDefinitionName" type="string">
  The name of the process definition that was started.
</ResponseField>

<ResponseField name="tokens" type="array">
  A list of tokens representing active workflow states within the process.
</ResponseField>

<ResponseField name="state" type="string">
  The current state of the process instance (e.g., "STARTED").
</ResponseField>

<ResponseField name="uuid" type="string">
  The unique identifier for the process instance.
</ResponseField>

<ResponseField name="instanceMetadata" type="object">
  Metadata related to the process instance, including:

  * `processInstanceId`: The numeric ID of the process instance.
  * `processInstanceUuid`: The UUID of the process instance.
</ResponseField>

### Response Headers

<ResponseField name="Access-Control-Allow-Credentials" type="boolean">
  Indicates whether the response can be exposed when credentials are present. Value is `true`.
</ResponseField>

<ResponseField name="Access-Control-Allow-Headers" type="string">
  Lists the allowed headers in the actual request. Example: `DNT, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization, flowx-platform`.
</ResponseField>

<ResponseField name="Access-Control-Allow-Methods" type="string">
  Specifies the allowed HTTP methods. Example: `GET, PUT, POST, DELETE, PATCH`.
</ResponseField>

<ResponseField name="Access-Control-Allow-Origin" type="string">
  Indicates the allowed origin for cross-origin requests. Example: `https://demo-angular.devmain.flowxai.dev`.
</ResponseField>

<ResponseField name="Content-Encoding" type="string">
  Specifies the encoding used to compress the response. Example: `gzip`.
</ResponseField>

<ResponseField name="Content-Type" type="string">
  Indicates the media type of the response content. Example: `application/json`.
</ResponseField>

<ResponseField name="Strict-Transport-Security" type="string">
  Enforces secure (HTTPS) connections to the server. Example: `max-age=31536000 ; includeSubDomains`.
</ResponseField>

<ResponseField name="Vary" type="string">
  Specifies that the response may vary based on the `Accept-Encoding` request header. Example: `Accept-Encoding`.
</ResponseField>

<ResponseField name="X-Content-Type-Options" type="string">
  Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`. Example: `nosniff`.
</ResponseField>

<ResponseField name="X-XSS-Protection" type="string">
  Controls the cross-site scripting (XSS) filter. Example: `0` (disabled).
</ResponseField>

<RequestExample>
  ```bash theme={"system"}
  curl -X POST "https://admin.devmain.flowxai.dev/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start" \
    -H "Authorization: Bearer <token>" \                    # Required
    -H "Content-Type: application/json" \                   # Required
    -H "flowx-platform: web" \                              # Required
    -H "Accept: application/json, text/plain, */*" \        # Optional
    -H "Accept-Encoding: gzip, deflate, br, zstd" \         # Optional
    -H "Accept-Language: en-GB,en-US;q=0.9,en;q=0.8" \      # Optional
    -d '{
      "key": "value"
    }'
  ```
</RequestExample>


# Start process by workspace, app, and process name
Source: https://docs.flowx.ai/5.9/docs/api/start-process/start-by-process-name

POST {BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start
Start a process using the workspace's active build — the simplest public REST entry point for triggering a FlowX process from your own backend or scheduled job.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

This is the recommended entry point when you want to start a process from outside FlowX (a backend service, a scheduled job, a partner system) and you do not want to manage `buildId` lookups yourself. The runtime resolves the active build for the given `(workspaceId, appId)` pair automatically.

If you need to pin to a specific build, use [Start process by build id and process name](./rest2) instead.

## Path parameters

<Info>
  **Need help finding these IDs?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide.
</Info>

<ParamField type="string">
  The ID of the workspace that owns the application.
</ParamField>

<ParamField type="string">
  The ID of the application. Must exist in the specified workspace.
</ParamField>

<ParamField type="string">
  The name of the process definition to start.
</ParamField>

## Request headers

<ParamField type="string">
  Bearer token from the configured identity provider. Format: `Bearer <token>`.
</ParamField>

<ParamField type="string">
  Must be `application/json`.
</ParamField>

## Request body

A JSON object with the initial process values. The exact shape depends on the process definition.

```json theme={"system"}
{
  "customerEmail": "alice@example.com",
  "loanAmount": 25000
}
```

## Response

Returns the new process instance, including its `uuid` (use this for subsequent calls) and `state`.

```json theme={"system"}
{
  "processDefinitionName": "customer_onboarding",
  "uuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d",
  "state": "STARTED",
  "applicationId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
  "buildId": "7d5560be-3846-49fa-9c17-4059c54c7c5f",
  "instanceMetadata": {
    "processInstanceUuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d"
  }
}
```

<RequestExample>
  ```bash theme={"system"}
  curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerEmail": "alice@example.com",
      "loanAmount": 25000
    }'
  ```
</RequestExample>


# Start process from UI with resource definition and inherit values
Source: https://docs.flowx.ai/5.9/docs/api/start-process/start-process-rdi-inherit

POST {BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}
Start a process by resource definition ID and inherit parameter values from a related process instance. Typically used from event handlers.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

## Base URL

* Always prepend the endpoint with the correct Base URL for your environment.
* For different environments (like staging or production), switch the base URL accordingly.

## Path Parameters

<Info>
  **Need help finding these IDs?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for detailed instructions on where to locate these values in FlowX Designer.
</Info>

<Warning>
  The combination of `workspaceId`, `appId`, and `resourceDefinitionId` must be valid and associated in the system. The `processInstanceId` must reference an existing process instance from which values will be inherited.
</Warning>

<ParamField type="string">
  The ID of the workspace where the process will be started. This parameter is now required to support multi-workspace environments.
</ParamField>

<ParamField type="string">
  The ID of the application in which the process will be started.
</ParamField>

<ParamField type="string">
  The ID of the resource definition that defines the process to be started. This is typically used when starting processes from event handlers.
</ParamField>

<ParamField type="string">
  The UUID of the related process instance from which parameter values will be inherited. This allows the new process to start with data from an existing process.
</ParamField>

## Request Headers

<ParamField type="string">
  Bearer token required for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField type="string">
  Indicates the media type of the request body. Must be set to `application/json`.
</ParamField>

<ParamField type="string">
  Identifies the client platform (e.g., `web`, `mobile`).
</ParamField>

<ParamField type="string">
  Specifies the media types that are acceptable for the response. Example: `application/json, text/plain, */*`.
</ParamField>

<ParamField type="string">
  Indicates supported content encoding algorithms for the response. Example: `gzip, deflate, br, zstd`.
</ParamField>

<ParamField type="string">
  Specifies language preferences for the response. Example: `en-GB,en-US;q=0.9,en;q=0.8`.
</ParamField>

## Request Body

The request body should contain a `paramsToInherit` object that controls which parameter values are inherited from the related process instance.

<ParamField type="object">
  A map containing information about which values to copy from the related process instance. This object can contain one of the following keys:

  * **`paramsToCopy`** (array of strings): Use this to pick only a subset of parameters to be inherited from the parent process. It holds the list of key names that will be inherited from the parent parameters.
  * **`withoutParams`** (array of strings): Use this to remove specific parameter values from the parent process before inheriting them. It holds the list of key names that will be removed from the parent parameters.

  If neither key is provided or both are empty, all parameter values from the parent process will be inherited by the new process.
</ParamField>

### Example Request Body

<CodeGroup>
  ```json Inherit specific parameters theme={"system"}
  {
    "paramsToInherit": {
      "paramsToCopy": ["customerName", "customerId", "accountType"]
    }
  }
  ```

  ```json Exclude specific parameters theme={"system"}
  {
    "paramsToInherit": {
      "withoutParams": ["temporaryToken", "sessionData"]
    }
  }
  ```

  ```json Inherit all parameters theme={"system"}
  {
    "paramsToInherit": {}
  }
  ```
</CodeGroup>

<Tip>
  When designing your process inheritance strategy, consider which parameters are truly needed in the new process. Use `paramsToCopy` for explicit control or `withoutParams` to exclude sensitive or temporary data.
</Tip>

## Response

<ResponseField name="processDefinitionFlowxUuid" type="string">
  The unique identifier of the process definition within FlowX.
</ResponseField>

<ResponseField name="buildId" type="string">
  The ID of the build associated with the process.
</ResponseField>

<ResponseField name="buildStatusAtStart" type="string">
  The status of the build at the time the process was started (e.g., "COMMITTED").
</ResponseField>

<ResponseField name="applicationId" type="string">
  The ID of the application where the process was initiated.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The ID of the workspace where the process was started.
</ResponseField>

<ResponseField name="parentApplicationId" type="string or null">
  The ID of the parent application if applicable, otherwise `null`.
</ResponseField>

<ResponseField name="rootApplicationId" type="string or null">
  The ID of the root application if applicable, otherwise `null`.
</ResponseField>

<ResponseField name="processDefinitionName" type="string">
  The name of the process definition that was started.
</ResponseField>

<ResponseField name="tokens" type="array">
  A list of tokens representing active workflow states within the process.
</ResponseField>

<ResponseField name="state" type="string">
  The current state of the process instance (e.g., "STARTED").
</ResponseField>

<ResponseField name="uuid" type="string">
  The unique identifier for the newly created process instance.
</ResponseField>

<ResponseField name="instanceMetadata" type="object">
  Metadata related to the process instance, including:

  * `processInstanceId`: The numeric ID of the process instance.
  * `processInstanceUuid`: The UUID of the process instance.
</ResponseField>

### Response Headers

<ResponseField name="Access-Control-Allow-Credentials" type="boolean">
  Indicates whether the response can be exposed when credentials are present. Value is `true`.
</ResponseField>

<ResponseField name="Access-Control-Allow-Headers" type="string">
  Lists the allowed headers in the actual request.
</ResponseField>

<ResponseField name="Access-Control-Allow-Methods" type="string">
  Specifies the allowed HTTP methods.
</ResponseField>

<ResponseField name="Access-Control-Allow-Origin" type="string">
  Indicates the allowed origin for cross-origin requests.
</ResponseField>

<ResponseField name="Content-Encoding" type="string">
  Specifies the encoding used to compress the response.
</ResponseField>

<ResponseField name="Content-Type" type="string">
  Indicates the media type of the response content.
</ResponseField>

<ResponseField name="Strict-Transport-Security" type="string">
  Enforces secure (HTTPS) connections to the server.
</ResponseField>

<ResponseField name="X-Content-Type-Options" type="string">
  Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`.
</ResponseField>

<ResponseField name="X-XSS-Protection" type="string">
  Controls the cross-site scripting (XSS) filter.
</ResponseField>

<RequestExample>
  ```bash cURL - Inherit specific parameters theme={"system"}
  curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -H "flowx-platform: web" \
    -H "Accept: application/json" \
    -d '{
      "paramsToInherit": {
        "paramsToCopy": ["customerName", "customerId", "accountType"]
      }
    }'
  ```

  ```bash cURL - Exclude specific parameters theme={"system"}
  curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -H "flowx-platform: web" \
    -H "Accept: application/json" \
    -d '{
      "paramsToInherit": {
        "withoutParams": ["temporaryToken", "sessionData"]
      }
    }'
  ```

  ```bash cURL - Inherit all parameters theme={"system"}
  curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -H "flowx-platform: web" \
    -H "Accept: application/json" \
    -d '{
      "paramsToInherit": {}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"system"}
  {
    "processDefinitionFlowxUuid": "66e74ea1-0775-42b4-b27e-a4a21ea78dfc",
    "buildId": "7d5560be-3846-49fa-9c17-4059c54c7c5f",
    "buildStatusAtStart": "COMMITTED",
    "applicationId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
    "workspaceId": "ws-123456789",
    "parentApplicationId": null,
    "rootApplicationId": null,
    "processDefinitionName": "customer_onboarding_child",
    "tokens": [
      {
        "id": 2112691,
        "state": "ACTIVE",
        "statusCurrentNode": "ARRIVED"
      }
    ],
    "state": "STARTED",
    "uuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d",
    "instanceMetadata": {
      "processInstanceId": 2112617,
      "processInstanceUuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d"
    }
  }
  ```
</ResponseExample>

## Triggering from FlowX Designer

This endpoint is triggered through a **Send data to user interface** node action configured in FlowX Designer:

<Steps>
  <Step title="Add node action">
    Add a **Send data to user interface** action to the node where you want to trigger the child process.
  </Step>

  <Step title="Configure message type">
    Set the **Message type** to `action` to enable process triggering capabilities.
  </Step>

  <Step title="Configure inheritance parameters">
    In the action configuration, specify which parameters should be inherited using `paramsToCopy` or `withoutParams` in the action payload.
  </Step>
</Steps>

<Info>
  For detailed instructions on configuring node actions in FlowX Designer, see the [Managing a Process Flow](../../flowx-designer/managing-a-project-flow/starting-a-process) documentation.
</Info>

## Use Cases

This endpoint is particularly useful for:

* **Multi-step workflows**: Starting a child process that continues work begun in a parent process
* **Process chaining**: Creating related processes that share common data
* **UI-triggered actions**: Starting processes from user interface actions that need to carry over existing data
* **Data inheritance**: Maintaining context across related process instances while controlling which data is passed forward

<Note>
  This endpoint is specifically designed for runtime operations initiated from event handlers. The `workspaceId` parameter ensures proper isolation in multi-tenant environments.
</Note>


# Start process and copy data from another instance
Source: https://docs.flowx.ai/5.9/docs/api/start-process/start-with-copy-data

POST {BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start/copyDataFrom/{processInstanceId}
Start a new process whose initial data is copied from an existing process instance — useful for retry, resume, and clone-like workflows.

<Tip>
  Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).
</Tip>

Start a new process instance and seed its data from a previously executed process instance. The new process picks up the data values that were on the source instance at the moment of the call.

Common use cases:

* Replaying a failed workflow with the same input
* Cloning an existing case for a similar customer
* Resuming downstream processing after an interruption

## Path parameters

<ParamField type="string">
  The ID of the workspace that owns the application.
</ParamField>

<ParamField type="string">
  The ID of the application.
</ParamField>

<ParamField type="string">
  The name of the process definition to start.
</ParamField>

<ParamField type="string">
  The UUID of the source process instance. Its data is copied into the new instance at start time.
</ParamField>

## Request headers

<ParamField type="string">
  Bearer token. Format: `Bearer <token>`.
</ParamField>

<ParamField type="string">
  Must be `application/json`.
</ParamField>

## Request body

A JSON object with values to merge on top of the copied data. Pass `{}` to start with the source instance's data unchanged.

```json theme={"system"}
{
  "retryReason": "manual-rerun",
  "operatorId": "u-9023"
}
```

## Response

Same shape as [Start process by workspace, app, and process name](./start-by-process-name) — the new instance's `uuid`, `state`, and metadata.

<RequestExample>
  ```bash theme={"system"}
  curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start/copyDataFrom/{processInstanceId}" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "retryReason": "manual-rerun"
    }'
  ```
</RequestExample>


# Container app authentication
Source: https://docs.flowx.ai/5.9/docs/saas/container-app-authentication

Configure authentication flows, landing pages, and session management for container applications that embed FlowX UI Flows.

## Overview

A **container app** is any web or mobile application that embeds FlowX UI Flows using the FlowX renderers (Angular, React, React Native, iOS, or Android SDKs). Container apps are responsible for authenticating end users before rendering FlowX content.

The container app authentication flow provides built-in support for OAuth2/OIDC authentication, custom landing pages, and session management.

***

## Key features

<CardGroup>
  <Card title="Authentication providers" icon="key">
    Support for multiple OAuth2/OIDC authentication providers via Keycloak integration
  </Card>

  <Card title="Custom landing page" icon="house">
    Configure a landing page for unauthenticated users with organization branding
  </Card>

  <Card title="Session management" icon="id-badge">
    Automatic token refresh, silent refresh support, and redirect URI persistence
  </Card>

  <Card title="SSO integration" icon="right-to-bracket">
    Single sign-on across container apps within the same organization
  </Card>
</CardGroup>

***

## How it works

The container app authentication flow handles the following:

<Steps>
  <Step title="Organization resolution">
    The container app resolves the organization context using the hostname or an organization code. This determines which Keycloak realm and authentication configuration to use.
  </Step>

  <Step title="Authentication redirect">
    Unauthenticated users are redirected to the configured identity provider (Keycloak) for login. The redirect URI is persisted in local storage to restore the user's navigation state after authentication.
  </Step>

  <Step title="Token management">
    After successful authentication, the container app manages access tokens with automatic refresh. Silent refresh keeps the session alive without requiring user interaction.
  </Step>

  <Step title="UI Flow rendering">
    Once authenticated, the container app renders FlowX UI Flows with the user's identity and permissions.
  </Step>
</Steps>

***

## Configuration

### Authentication setup

Container apps authenticate using OAuth2/OIDC with the following configuration:

| Parameter             | Description                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Organization code** | Identifies the organization for multi-tenant environments. Can be derived from the hostname or provided explicitly. |
| **Keycloak realm**    | The Keycloak realm associated with the organization                                                                 |
| **Client ID**         | The OAuth2 client ID registered in Keycloak for the container app                                                   |
| **Redirect URI**      | The URI to redirect to after authentication. Persisted across browser sessions.                                     |

<Tip>
  For multi-tenant SaaS deployments, the organization code is typically extracted from the subdomain (e.g., `acme.flowx.ai` resolves to organization `acme`).
</Tip>

### Landing page

You can configure a custom landing page that appears for unauthenticated users. This page can include:

* Organization branding and logo
* Login button that initiates the authentication flow
* Links to support or documentation

<Card title="Container app branding" icon="palette" href="./container-app-branding">
  Customize colors, logo, and header appearance for the container app
</Card>

### Session behavior

| Behavior                 | Description                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| **Token refresh**        | Access tokens are refreshed automatically before expiration        |
| **Silent refresh**       | Background token renewal without user interaction                  |
| **Redirect persistence** | The user's intended destination is stored and restored after login |
| **Session timeout**      | Configurable session duration based on Keycloak realm settings     |

***

## SDK integration

Each FlowX renderer SDK handles container app authentication:

<Tabs>
  <Tab title="Angular">
    The Angular SDK integrates with `angular-oauth2-oidc` for authentication handling. Configure the OAuth2 module in your app with the Keycloak endpoints for your organization.

    For setup details, see the [Angular SDK documentation](/5.9/sdks/angular-renderer).
  </Tab>

  <Tab title="React">
    The React SDK provides authentication hooks that connect to your Keycloak instance.

    For setup details, see the [React SDK documentation](/5.9/sdks/react-renderer).
  </Tab>

  <Tab title="React Native">
    The React Native SDK is being introduced in FlowX.AI 5.9.0. Authentication integration details will be added once the SDK ships.

    For setup details, see the [React Native SDK documentation](/5.9/sdks/react-native-renderer).
  </Tab>

  <Tab title="iOS">
    The iOS renderer handles OAuth2 authentication natively with secure token storage in the keychain.

    For setup details, see the [iOS SDK documentation](/5.9/sdks/ios-renderer).
  </Tab>

  <Tab title="Android">
    The Android renderer integrates with AppAuth for secure OAuth2 authentication.

    For setup details, see the [Android SDK documentation](/5.9/sdks/android-renderer).
  </Tab>
</Tabs>

***

## Related resources

<CardGroup>
  <Card title="IAM Configuration" icon="key" href="/5.9/setup-guides/access-management/configuring-an-iam-solution">
    Set up Keycloak realms, clients, and service accounts
  </Card>

  <Card title="UI Flows" icon="window-maximize" href="/5.9/docs/building-blocks/ui-flows">
    Learn about UI Flows and how they render in container apps
  </Card>

  <Card title="FlowX SaaS Overview" icon="cloud" href="/5.9/docs/saas/saas-overview">
    Understand the FlowX SaaS deployment model
  </Card>

  <Card title="Workspaces & Access Rights" icon="shield" href="/5.9/setup-guides/access-management/workspaces-access-rights">
    Configure workspace-level access control
  </Card>
</CardGroup>


# Container app branding
Source: https://docs.flowx.ai/5.9/docs/saas/container-app-branding

Customize the visual appearance of the SaaS container app with organization-level branding settings.

## Overview

**Container app branding** lets organization administrators customize the visual appearance of the SaaS container app — the runtime that wraps FlowX solutions for end users. Branding settings apply organization-wide across all workspaces and projects.

<CardGroup>
  <Card title="Custom colors" icon="paintbrush">
    Set primary, secondary, header, and page background colors
  </Card>

  <Card title="Logo upload" icon="image">
    Replace the default logo with your organization's branding
  </Card>

  <Card title="Header control" icon="toggle-on">
    Show or hide the container app header (useful for iframe embeds)
  </Card>

  <Card title="Live preview" icon="eye">
    Preview branding changes before saving
  </Card>
</CardGroup>

***

## Accessing branding settings

To configure branding:

1. Navigate to **Organization Admin** in FlowX Designer
2. Select **Generic App Branding** under **Design Assets**

<Info>
  Branding settings require the `org_branding_read` permission to view and `org_branding_edit` permission to modify.
</Info>

The branding page has a form panel on the left and a live preview on the right. Use the layout toggle in the header to switch between flat view, accordion view, or form-only mode.

***

## Branding properties

### General

<ParamField type="hex color">
  Accent color used for buttons, active states, and interactive elements on the solutions page.
</ParamField>

<ParamField type="hex color">
  Used for avatar backgrounds and secondary accents.
</ParamField>

***

### Header

<ParamField type="boolean">
  Toggle the container app header on or off.

  **Default:** ON

  <Tip>
    Turn off the header when embedding the container app in an iframe where the parent app provides its own navigation.
  </Tip>
</ParamField>

<ParamField type="file upload">
  Custom logo displayed in the header. Replaces the default FlowX logo.

  **Supported formats:** PNG, JPG, SVG, WEBP

  **Max file size:** 2 MB
</ParamField>

<ParamField type="hex color">
  Header background color.

  **Default:** `#2A313A`
</ParamField>

<ParamField type="preset">
  Header drop shadow. Choose from preset sizes or turn off completely.

  **Options:** None, XS, S, M, L, XL

  Each preset configures the shadow color, opacity, and blur radius.
</ParamField>

***

### Solutions page

<ParamField type="hex color">
  Background color of the solutions landing page where users select which solution to open.
</ParamField>

***

## How branding is applied

When an end user loads the container app:

1. The app resolves the organization context (from the hostname or organization code)
2. Branding configuration is included in the organization lookup API response
3. The container app applies branding values as CSS custom properties
4. Colors, logo, and header settings take effect immediately

<Info>
  Branding is applied before authentication, so the login landing page also reflects the organization's branding.
</Info>

***

## Related resources

<CardGroup>
  <Card title="Container app authentication" icon="lock" href="./container-app-authentication">
    Configure authentication flows and session management for container apps
  </Card>

  <Card title="Organization settings" icon="building" href="./organization-settings">
    Manage organization-level configuration
  </Card>

  <Card title="FlowX SaaS overview" icon="cloud" href="./saas-overview">
    Understand the FlowX SaaS deployment model
  </Card>
</CardGroup>


# Inviting Users
Source: https://docs.flowx.ai/5.9/docs/saas/inviting-users

Learn how Organization Admins can invite designer users to their organization via email with role assignments and secure activation.

## Overview

Organization Admins can invite designer users to their organization via email. Invited users receive a secure invitation link, can be pre-assigned roles and groups, and go through a guided activation flow before becoming active members.

<Note>
  Only users with the **Organization Admin** role can invite new designer users.
</Note>

<Info>
  **SMTP is required.** Invitations and password-recovery emails are dispatched by Keycloak. On self-hosted deployments the client must configure SMTP in Keycloak (per realm) before either flow will work — without it, invitations fail silently. See [Email (SMTP) configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#email-smtp-configuration).
</Info>

## Accessing user invitations

The invitation feature is available from the Designer Users page:

<Steps>
  <Step title="Navigate to Designer Users">
    Go to **Organization Settings** → **Designer Users**
  </Step>

  <Step title="Open the invite dialog">
    Click **Invite User** from the contextual menu or action bar

    <Frame>
      ![Invite User button in Designer Users page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mti3.png)
    </Frame>
  </Step>
</Steps>

## Invitation form

When inviting a new user, you can configure the following options:

| Field               | Required | Description                              |
| ------------------- | -------- | ---------------------------------------- |
| **email address**   | Yes      | Valid email format for the invitation    |
| **Designer role**   | No       | Organization Admin or Organization Owner |
| **Runtime Roles**   | No       | Assign runtime roles to the user         |
| **Runtime Groups**  | No       | Add user to runtime groups               |
| **User attributes** | No       | Set custom user attributes               |

<Frame>
  ![Invitation form with email, roles, and groups fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/saas2.png)
</Frame>

<Tip>
  Pre-assigning roles and groups during invitation saves time and ensures users have the correct access from their first login.
</Tip>

## Invitation workflow

### Sending an invitation

<Steps>
  <Step title="Enter email address">
    Provide the email address of the user you want to invite
  </Step>

  <Step title="Configure access (optional)">
    Select a designer role, runtime roles, groups, and any custom attributes
  </Step>

  <Step title="Send invitation">
    Click **Send invite** to create the user and trigger the invitation email
  </Step>
</Steps>

When you send an invitation:

1. A user account is created in Keycloak with:
   * The provided email address
   * Selected runtime roles and groups
   * email verified set to `false`
   * Required actions: update password and update profile

2. A user record is created in FlowX with:
   * Assigned selections (roles, groups, attributes)
   * Status: **Pending**
   * Organization Owner role (if selected)

3. An invitation email is sent to the user

<Check>
  A success notification confirms: "Invitation sent successfully"
</Check>

### Invitation email

The invited user receives an email with the following content:

<Frame>
  **Subject:** You've been invited to your FlowX.ai account

  Hi,

  You've been invited to join the FlowX Platform to test our new Agentic Apps.

  This early access will let you explore how Agentic Apps work and give feedback on the experience before the broader rollout.

  **\[Accept Invitation]**

  Best
</Frame>

<Warning>
  Invitation links are valid for **2 days**. After expiration, the user will need a new invitation.
</Warning>

## User activation flow

When the invited user clicks the invitation link, they complete a two-step activation process:

### Step 1: Set password

The user creates a secure password for their account:

* Minimum 8 characters, maximum 64 characters
* Must include at least one uppercase letter, one lowercase letter, one number, and one special character (`!@#$%^&*()_+-`)
* Cannot be the same as the user's email address
* Upon submission, proceeds to profile setup

### Step 2: Complete profile

The user provides their profile information:

| Field          | Required | Description       |
| -------------- | -------- | ----------------- |
| **First name** | Yes      | User's first name |
| **Last name**  | Yes      | User's last name  |

Upon submission:

* User profile is updated with the provided information
* email is marked as verified
* User is redirected to the login page with a success message

### First login

After completing activation and logging in for the first time:

* User status changes from **Pending** to **Active**
* First name and last name are populated in the FlowX user profile
* User appears in the Designer Users list with Active status

## Handling expired invitations

If a user clicks an invitation link after it has expired (more than 2 days), they see an "Invite link expired" page.

<Warning>
  To resolve an expired invitation, the Organization Admin needs to send a new invitation to the user.
</Warning>

## User statuses

| Status       | Description                                               |
| ------------ | --------------------------------------------------------- |
| **Pending**  | User has been invited but hasn't completed activation     |
| **Active**   | User has completed activation and logged in at least once |
| **Disabled** | User account has been deactivated by an administrator     |

### Disabling and enabling users

Administrators can change a user's status from the Designer Users or Runtime Users page:

<Steps>
  <Step title="Open user actions">
    Find the user in the users list and open the context menu (three-dot menu)
  </Step>

  <Step title="Select the action">
    Choose **Disable** to deactivate an active user, or **Enable** to reactivate a disabled user
  </Step>

  <Step title="Confirm the action">
    Confirm the action in the dialog. The user's status updates immediately.
  </Step>
</Steps>

<Note>
  The Disable/Enable actions are available only for **Runtime Users**. Disabled users cannot log in until their account is re-enabled.
</Note>

### Resending invitations

If a user's invitation has expired or was lost, you can resend it:

<Steps>
  <Step title="Find the pending user">
    Find the user with **Pending** status in the Designer Users or Runtime Users list.
  </Step>

  <Step title="Select Resend invite">
    Open the context menu and select **Resend invite**.
  </Step>

  <Step title="Invitation sent">
    A new invitation email is sent with a fresh activation link.
  </Step>
</Steps>

<Tip>
  Resend invitations are available for both Designer and Runtime users with Pending status.
</Tip>

## Best practices

<AccordionGroup>
  <Accordion title="Pre-assign appropriate roles">
    Configure the correct designer role and runtime roles during invitation to ensure users have proper access from day one.
  </Accordion>

  <Accordion title="Use runtime groups for team organization">
    Add users to runtime groups during invitation to automatically organize them into teams and apply group-based permissions.
  </Accordion>

  <Accordion title="Monitor pending invitations">
    Regularly check the Designer Users page for users with Pending status to identify invitations that may need to be resent.
  </Accordion>

  <Accordion title="Communicate invitation timing">
    Let invited users know to expect the invitation email and complete activation within 2 days to avoid expiration.
  </Accordion>
</AccordionGroup>

## Limitations

<Note>
  The following features are planned for future releases:

  * **Cancel invite** - Ability to cancel a pending invitation
  * **Copy invite link** - Ability to copy the invitation link directly
</Note>

## Related documentation

<CardGroup>
  <Card title="FlowX SaaS Overview" icon="cloud" href="/5.9/docs/saas/saas-overview">
    Learn about FlowX SaaS deployment and multi-tenancy
  </Card>

  <Card title="Access Management" icon="shield" href="/5.9/setup-guides/access-management/access-management-overview">
    Configure IAM and Keycloak settings
  </Card>

  <Card title="Workspaces" icon="folder" href="/5.9/docs/projects/workspaces">
    Understand workspace organization
  </Card>

  <Card title="Roles & Permissions" icon="user-lock" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    View the complete roles and permissions reference
  </Card>
</CardGroup>


# Organization settings
Source: https://docs.flowx.ai/5.9/docs/saas/organization-settings

Configure AI providers, manage access, design assets, and platform settings for your FlowX organization.

## Overview

Organization settings provide administrative controls for managing your FlowX organization. Access these settings from the left sidebar in FlowX Designer by clicking your organization name.

<Info>
  Organization settings require **Organization Admin** or **Organization Owner** roles.
</Info>

***

## Settings sections

<CardGroup>
  <Card title="Solutions" icon="rocket">
    View published solutions available for end users in the runtime container app.
  </Card>

  <Card title="Usage Stats" icon="chart-line">
    Monitor AI consumption metrics for your organization. Available when AI providers are configured — organizations that do not use AI features will not see meaningful data here.
  </Card>

  <Card title="Model Providers" icon="microchip-ai" href="/5.9/ai-platform/ai-providers">
    Configure LLM providers, manage API keys, and control which AI models are available across workspaces.
  </Card>

  <Card title="Workspaces" icon="folder" href="/5.9/docs/projects/workspaces">
    View and manage workspaces associated with your organization.
  </Card>
</CardGroup>

### Design Assets

<CardGroup>
  <Card title="Fonts" icon="font">
    Manage custom fonts available across your organization's UI Flows.
  </Card>

  <Card title="Branding" icon="palette" href="/5.9/docs/saas/container-app-branding">
    Configure branding settings for the container app (logo, colors, favicon).
  </Card>
</CardGroup>

### Access Management

<CardGroup>
  <Card title="Designer Users" icon="users" href="/5.9/docs/saas/inviting-users">
    Invite and manage users who build processes and workflows in FlowX Designer.
  </Card>

  <Card title="Designer Roles" icon="user-shield" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    Configure roles and permissions for Designer users.
  </Card>

  <Card title="End-Users" icon="user-group">
    Manage end users who access published solutions at runtime.
  </Card>

  <Card title="End-Users Roles" icon="id-badge">
    Define roles for end users to control access to specific solutions and features.
  </Card>

  <Card title="End-Users Groups" icon="users-rectangle">
    Organize end users into groups for role assignment and access control.
  </Card>
</CardGroup>

### Platform

<CardGroup>
  <Card title="Task Manager" icon="list-check">
    Configure task management settings including out-of-office schedules.
  </Card>

  <Card title="Platform Status" icon="circle-check">
    View installed component versions and service health status.
  </Card>

  <Card title="Audit Logs" icon="clipboard-list">
    Review organization-level audit trail for user actions and configuration changes.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="AI providers" icon="microchip-ai" href="/5.9/ai-platform/ai-providers">
    Configure LLM providers and model assignments
  </Card>

  <Card title="Workspaces" icon="folder" href="/5.9/docs/projects/workspaces">
    Organize projects and resources
  </Card>

  <Card title="Roles and permissions" icon="user-lock" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    Complete roles and permissions reference
  </Card>

  <Card title="Container app branding" icon="palette" href="/5.9/docs/saas/container-app-branding">
    Customize your runtime app appearance
  </Card>
</CardGroup>


# FlowX SaaS Overview
Source: https://docs.flowx.ai/5.9/docs/saas/saas-overview

Learn about FlowX.AI SaaS deployment model and multi-tenant architecture.

<Info>
  FlowX.AI is available as a managed SaaS offering. For self-managed deployments, see the [Setup Guides](/5.9/setup-guides/setup-guides-overview).
</Info>

## Deployment models

FlowX.AI is available in two deployment models:

<CardGroup>
  <Card title="Self-Hosted" icon="server">
    **Customer Cloud**

    Deploy FlowX.AI in your own infrastructure as a single-organization setup, with full control over configuration, security, and data residency.

    * Single-organization deployment
    * Complete infrastructure control
    * Custom security configurations
    * Data residency compliance
  </Card>

  <Card title="FlowX SaaS" icon="cloud">
    **FlowX-hosted**

    Get started quickly with FlowX.AI hosted and managed by FlowX, with automatic updates and maintenance.

    * Automatic provisioning
    * Managed infrastructure
    * Built-in multi-tenancy
    * Automatic updates
  </Card>
</CardGroup>

<Info>
  **Self-hosted licensing**

  Self-hosted deployments connect to the FlowX SaaS licensing infrastructure for license validation and usage reporting. The License service on your environment communicates with the FlowX SaaS license server. Ensure your network allows outbound connectivity to the FlowX SaaS endpoints provided during setup.

  For more details, see the [License service setup guide](/5.9/setup-guides/license-engine-setup).
</Info>

## Available regions

FlowX SaaS is available in the following regions:

<CardGroup>
  <Card title="European Union" icon="earth-europe">
    Hosted in the EU for organizations requiring European data residency.
  </Card>

  <Card title="United States" icon="earth-americas">
    Hosted in the US for organizations requiring North American data residency.
  </Card>
</CardGroup>

***

## Updates and maintenance

FlowX manages all platform updates and maintenance for SaaS environments. No action is required from your team.

***

## Workspace types

Each workspace in FlowX SaaS is assigned a type that indicates its purpose in the delivery lifecycle:

| Workspace Type  | Purpose                                      |
| --------------- | -------------------------------------------- |
| **Development** | Building and iterating on apps and workflows |
| **Staging**     | Testing and validation before production     |
| **Production**  | Live environment serving end users           |

The workspace type is visible in the Designer workspace selector, so you can identify which environment you are working in.

***

## FlowX SaaS capabilities

FlowX SaaS provides a secure multi-tenant platform with organization management and tenant isolation.

**Multi-tenant architecture**

FlowX SaaS implements workspace-level isolation to ensure data security across organizations:

<CardGroup>
  <Card title="Authentication isolation" icon="key">
    Each organization has its own identity provider
  </Card>

  <Card title="Database isolation" icon="database">
    Each organization has its own database
  </Card>

  <Card title="Resource isolation" icon="folder">
    Each organization has its own resources
  </Card>
</CardGroup>


# EU AI Act
Source: https://docs.flowx.ai/5.9/observatory/compliance/eu-ai-act

18 EU AI Act requirements mapped to Observatory controls, with scope by risk tier.

Observatory ships with 18 EU AI Act requirements pre-mapped to operational controls. The scope of each requirement depends on the **risk tier** of the app (minimal / limited / high), set in the [AI Registry](../governance/ai-registry).

***

## Requirement scope by risk tier

| Risk tier        | Number of EU AI Act requirements in scope |
| ---------------- | ----------------------------------------- |
| **Minimal**      | Transparency obligations only             |
| **Limited**      | Transparency + user information           |
| **High**         | All 18 requirements                       |
| **Unacceptable** | Banned — flagged for removal              |

If an app's tier is set incorrectly, the wrong requirements light up. Confirm the tier before reading status.

***

## The 18 mapped requirements

These are grouped roughly along the Act's structure. Observatory tracks them individually; the grouping is for readability.

### Risk management and quality (Articles 9, 17)

| Requirement               | Backing controls             |
| ------------------------- | ---------------------------- |
| Risk management system    | Risk Dashboard + Assessments |
| Quality management system | Audit Trail + Evidence       |

### Data and data governance (Article 10)

| Requirement                 | Backing controls                                        |
| --------------------------- | ------------------------------------------------------- |
| Training data governance    | Manual evidence (data lineage docs)                     |
| Validation and testing data | Datasets + Experiments                                  |
| Bias detection in training  | Manual evidence + drift monitor on protected attributes |

### Technical documentation (Articles 11, 12, 13)

| Requirement              | Backing controls                     |
| ------------------------ | ------------------------------------ |
| Technical documentation  | Manual evidence + registry metadata  |
| Record-keeping (logging) | Telemetry + 7-year retention setting |
| Transparency to users    | Manual evidence + UI screenshots     |

### Human oversight (Article 14)

| Requirement         | Backing controls                   |
| ------------------- | ---------------------------------- |
| Human-in-the-loop   | Manual evidence + tool definitions |
| Override mechanisms | Manual evidence                    |

### Accuracy and robustness (Article 15)

| Requirement          | Backing controls                          |
| -------------------- | ----------------------------------------- |
| Accuracy levels      | Evaluations + Experiments                 |
| Cybersecurity        | Policies (prompt-injection) + Audit Trail |
| Robustness to errors | Alerts + Drift Monitor                    |

### Post-market monitoring (Article 61)

| Requirement                 | Backing controls                         |
| --------------------------- | ---------------------------------------- |
| Post-market monitoring plan | Manual evidence (the plan document)      |
| Continuous monitoring data  | Telemetry + Analytics                    |
| Serious-incident reporting  | Alerts with `incident` tag + Audit Trail |

### Notifications (Article 62)

| Requirement                 | Backing controls                            |
| --------------------------- | ------------------------------------------- |
| Conformity assessment       | Assessments template                        |
| Registration in EU database | Manual evidence (registration confirmation) |

***

## Status semantics

Each requirement evaluates to:

* **Met** — all backing controls have approved, in-date evidence
* **Partial** — some controls met, others have gaps
* **Gap** — at least one control has no current evidence
* **Out of scope** — risk tier doesn't trigger this requirement

The Article-level roll-up is the worst status of its requirements (any Gap → Gap).

***

## Producing the audit pack

The EU AI Act view supports a one-click export of the audit pack:

* Per-requirement evidence list with timestamps
* Backing telemetry summaries
* Assessment results
* Gap analysis with remediation plan

```http theme={"system"}
POST /api/compliance/export?framework=eu-ai-act&app_id=...
```

Returns a ZIP with PDF and JSON outputs.

***

## Related resources

<CardGroup>
  <Card title="Gap analysis & heatmap" icon="grid" href="./gap-analysis-heatmap">
    Cross-framework view that includes EU AI Act.
  </Card>

  <Card title="NIST AI RMF" icon="flag" href="./nist-ai-rmf">
    Many EU AI Act requirements overlap with NIST controls.
  </Card>
</CardGroup>


# Gap analysis & heatmap
Source: https://docs.flowx.ai/5.9/observatory/compliance/gap-analysis-heatmap

Cross-framework view that prioritises remediation by the impact of closing each gap.

The gap analysis and heatmap views answer two questions at once: where do we stand against every framework, and where will one piece of work move the most needles?

***

## The heatmap

Each cell in the heatmap is one requirement × one framework. The colour is the status:

| Colour | Status       |
| ------ | ------------ |
| Green  | Met          |
| Yellow | Partial      |
| Red    | Gap          |
| Grey   | Out of scope |

Reading the heatmap horizontally tells you about cross-framework overlap. A red row across all three frameworks means closing that single requirement closes three gaps at once.

***

## Gap analysis

The gap analysis is the heatmap pivoted: list of all open gaps, sorted by remediation impact.

### Sort options

| Sort by                    | Use for                          |
| -------------------------- | -------------------------------- |
| **Cross-framework impact** | Maximise leverage. Default sort. |
| **Severity**               | Tackle the worst gaps first.     |
| **Estimated effort**       | Quick wins first.                |
| **Framework**              | Scope to one auditor's view.     |

### What "impact" measures

A single requirement's impact is `count of frameworks affected × max severity`. So an EU AI Act high-severity gap that also fails NIST and ISO 42001 outranks an isolated low-severity gap, even if the latter looks scarier individually.

***

## Reading the heatmap

<Steps>
  <Step title="Start with the rows">
    Sort by severity descending. The top rows are the most painful gaps.
  </Step>

  <Step title="Look at the row's colour pattern">
    A row red across all three columns is high-leverage. A row red in one column only is framework-specific.
  </Step>

  <Step title="Click the cell">
    Each cell drills into the requirement detail — backing controls, current evidence, what's missing.
  </Step>

  <Step title="Take action">
    Either provide manual evidence, schedule an [assessment](../governance/assessments), or fix the underlying telemetry/policy that drives the control.
  </Step>
</Steps>

***

## Exporting

Both views support PDF and CSV export. The exported gap analysis is the format most GRC teams paste into their tracking tool.

```http theme={"system"}
POST /api/compliance/heatmap/export
GET  /api/compliance/gaps?sort=impact
```

***

## Related resources

<CardGroup>
  <Card title="Evidence" icon="folder-open" href="../governance/evidence">
    The mechanism for closing manual-evidence gaps.
  </Card>

  <Card title="Compliance overview" icon="circle-check" href="./overview">
    Per-framework views the heatmap aggregates.
  </Card>
</CardGroup>


# ISO 42001
Source: https://docs.flowx.ai/5.9/observatory/compliance/iso-42001

12 ISO/IEC 42001:2023 requirements mapped to Observatory controls for AI management systems.

ISO/IEC 42001:2023 is the international standard for AI management systems. Observatory maps 12 of its key clauses to operational controls. Unlike the EU AI Act (regulatory) and NIST RMF (voluntary framework), ISO 42001 is the certifiable standard your auditor will audit against.

***

## What ISO 42001 expects

ISO 42001 follows the same plan-do-check-act structure as other ISO management-system standards (9001, 27001). Observatory's mappings focus on the AI-specific clauses where evidence is hardest to gather by hand.

***

## Mapped clauses

| Clause | Title                               | Backing controls                  |
| ------ | ----------------------------------- | --------------------------------- |
| 4.1    | Understanding the organization      | AI Registry + manual evidence     |
| 4.4    | AI management system scope          | Manual evidence (scope document)  |
| 5.1    | Leadership and commitment           | Manual evidence                   |
| 6.1    | Actions for risks and opportunities | Risk Dashboard + Assessments      |
| 7.4    | Communication                       | Audit Trail + Alerts              |
| 7.5    | Documented information              | Evidence + retention setting      |
| 8.1    | Operational planning and control    | Policies + Audit Trail            |
| 8.4    | AI system development               | Assessments (release-readiness)   |
| 8.5    | Operation                           | Telemetry + Drift Monitor         |
| 9.1    | Performance evaluation              | Analytics + Experiments           |
| 9.2    | Internal audit                      | Audit Trail + manual evidence     |
| 10.1   | Continual improvement               | Manual evidence (improvement log) |

***

## Status semantics

ISO 42001 audits typically reach a binary conformance per clause. Observatory's three-state status reflects how close you are to that bar:

* **Met** — conformant
* **Partial** — conformant for some sub-elements only (likely a finding at audit)
* **Gap** — non-conformant
* **Out of scope** — clause excluded from scope statement (rare)

***

## What auditors typically want

Most ISO 42001 auditors ask for:

1. The AI management system scope document (clause 4.4) — manual evidence
2. Risk register with treatment plans (clause 6.1) — Risk Dashboard export + treatment notes
3. Records of operational telemetry (clauses 7.5, 8.5) — Observatory's standard retention
4. Internal audit reports (clause 9.2) — manual evidence
5. Continual-improvement evidence (clause 10.1) — improvement log

The export bundle covers items 2 and 3 directly; items 1, 4, and 5 need manual evidence in Observatory.

```http theme={"system"}
POST /api/compliance/export?framework=iso-42001&app_id=...
```

***

## Overlap with EU AI Act

Clause 6.1 (risk treatment) overlaps with EU AI Act Article 9. Clause 8.5 (operation) overlaps with Article 17. The [gap analysis](./gap-analysis-heatmap) treats these as joint priorities.

***

## Related resources

<CardGroup>
  <Card title="EU AI Act" icon="building" href="./eu-ai-act">
    Regulatory framework that overlaps with ISO 42001 risk treatment.
  </Card>

  <Card title="Audit Trail" icon="clipboard-list" href="../governance/overview">
    Where ISO auditors expect to find every change.
  </Card>
</CardGroup>


# NIST AI RMF
Source: https://docs.flowx.ai/5.9/observatory/compliance/nist-ai-rmf

16 NIST AI Risk Management Framework requirements mapped to Observatory controls across Govern, Map, Measure, Manage.

NIST AI RMF organises risk management around four functions: **Govern**, **Map**, **Measure**, **Manage**. Observatory maps 16 of the framework's high-impact subcategories to operational controls.

***

## The four functions

```mermaid theme={"system"}
flowchart LR
    Govern["Govern<br/>(culture, policy, accountability)"] --> Map
    Map["Map<br/>(context, classification, scope)"] --> Measure
    Measure["Measure<br/>(testing, monitoring, evaluation)"] --> Manage
    Manage["Manage<br/>(prioritise, treat, communicate)"] -.feedback.-> Govern
```

A healthy AI RMF posture closes the loop: governance decisions feed mapping, mapping feeds measurement, measurement feeds management, and management updates governance.

***

## Mapped subcategories

### Govern (4 mapped)

| Subcategory                              | Backing controls                      |
| ---------------------------------------- | ------------------------------------- |
| Govern 1.1 — policies and procedures     | Policies + Audit Trail                |
| Govern 1.4 — accountability and roles    | RBAC + AI Registry ownership          |
| Govern 4.1 — AI risk management training | Manual evidence                       |
| Govern 5.1 — communication channels      | Manual evidence (incident-comms plan) |

### Map (4 mapped)

| Subcategory                            | Backing controls              |
| -------------------------------------- | ----------------------------- |
| Map 1.1 — AI system context            | AI Registry metadata          |
| Map 1.2 — intended use and limitations | AI Registry + manual evidence |
| Map 3.3 — record-keeping               | Telemetry + retention setting |
| Map 5.1 — third-party AI components    | AI Registry vendor section    |

### Measure (4 mapped)

| Subcategory                         | Backing controls                       |
| ----------------------------------- | -------------------------------------- |
| Measure 1.1 — relevant metrics      | Analytics                              |
| Measure 2.3 — performance over time | Drift Monitor                          |
| Measure 2.7 — security tests        | Policies (prompt-injection) + Evidence |
| Measure 4.2 — feedback mechanisms   | Thread feedback + Evidence             |

### Manage (4 mapped)

| Subcategory                              | Backing controls           |
| ---------------------------------------- | -------------------------- |
| Manage 1.1 — prioritise risks            | Risk Dashboard             |
| Manage 2.3 — incident response           | Alerts + Audit Trail       |
| Manage 3.1 — manage third-party risks    | AI Registry vendor section |
| Manage 4.1 — communicate to stakeholders | Compliance heatmap export  |

***

## Overlap with EU AI Act

Several NIST subcategories overlap directly with [EU AI Act](./eu-ai-act) requirements:

| NIST subcategory | Overlaps with                                |
| ---------------- | -------------------------------------------- |
| Govern 1.1       | EU AI Act Article 9 (risk management)        |
| Map 3.3          | EU AI Act Article 12 (record-keeping)        |
| Measure 2.3      | EU AI Act Article 15 (robustness)            |
| Manage 2.3       | EU AI Act Article 62 (incident notification) |

Closing one usually closes both. The [gap analysis](./gap-analysis-heatmap) prioritises remediation by cross-framework impact.

***

## Producing the audit pack

Same shape as EU AI Act: a ZIP with per-subcategory evidence and the framework score.

```http theme={"system"}
POST /api/compliance/export?framework=nist-ai-rmf&app_id=...
```

***

## Related resources

<CardGroup>
  <Card title="EU AI Act" icon="building" href="./eu-ai-act">
    Sister framework with significant overlap.
  </Card>

  <Card title="Risk Dashboard" icon="triangle-exclamation" href="../governance/risk-dashboard">
    Where Manage 1.1 (prioritise risks) is operationalised.
  </Card>
</CardGroup>


# Compliance
Source: https://docs.flowx.ai/5.9/observatory/compliance/overview

EU AI Act, NIST AI RMF, and ISO 42001 mapped to your runtime — controls evaluated continuously, gaps surfaced automatically.

Compliance turns governance work into framework-specific status you can put in front of an auditor. Each framework's requirements are pre-mapped to Observatory controls; the controls evaluate continuously against your telemetry, evidence, and assessments.

***

## Frameworks covered

<CardGroup>
  <Card title="EU AI Act" icon="building" href="./eu-ai-act">
    18 requirements mapped, with scope by risk tier (minimal / limited / high).
  </Card>

  <Card title="NIST AI RMF" icon="flag" href="./nist-ai-rmf">
    16 requirements across Govern, Map, Measure, Manage.
  </Card>

  <Card title="ISO 42001" icon="globe" href="./iso-42001">
    12 requirements for AI management systems.
  </Card>

  <Card title="Gap analysis & heatmap" icon="grid" href="./gap-analysis-heatmap">
    Cross-framework view with prioritised remediation.
  </Card>
</CardGroup>

***

## How a control becomes a status

```mermaid theme={"system"}
flowchart LR
    Framework[Framework requirement] --> Controls[Mapped Observatory controls]
    Controls --> Inputs{Inputs}
    Inputs --> Telemetry[Telemetry]
    Inputs --> Policy[Policy evaluations]
    Inputs --> Evidence[Approved evidence]
    Inputs --> Assessment[Assessment answers]
    Telemetry & Policy & Evidence & Assessment --> Status[Per-control status]
    Status --> Roll[Framework score]
```

Each requirement maps to one or more controls. Each control draws on the same operational inputs (telemetry, policies, evidence, assessments). Status is one of:

* **Met** — sufficient approved evidence within freshness window
* **Partial** — some evidence but gaps remain
* **Gap** — no current evidence
* **Out of scope** — risk tier doesn't trigger this requirement

***

## When to use the compliance views

| Audience                          | Page                                                       |
| --------------------------------- | ---------------------------------------------------------- |
| Auditor preparing a review        | The framework page they care about + the heatmap export    |
| GRC team planning sprints         | Gap analysis sorted by severity                            |
| Security team checking posture    | Heatmap, scoped by risk tier                               |
| Engineering team during a release | Requirement detail for the one control that flipped to Gap |

***

## Cross-framework mapping

Many requirements overlap. Observatory's mapping engine recognises this — closing a gap in one framework often resolves a gap in another:

* EU AI Act Article 9 (risk management) overlaps with NIST RMF Govern-1.1 and ISO 42001 6.1.
* EU AI Act Article 12 (record-keeping) overlaps with NIST RMF Map-3.3 and ISO 42001 8.5.

The heatmap shows these overlaps; the gap analysis prioritises remediation by impact across frameworks.

***

## Related resources

<CardGroup>
  <Card title="Evidence" icon="folder-open" href="../governance/evidence">
    Where the artefacts that satisfy controls live.
  </Card>

  <Card title="AI Registry" icon="server" href="../governance/ai-registry">
    Risk tier in the registry determines which requirements apply.
  </Card>
</CardGroup>


# Getting started
Source: https://docs.flowx.ai/5.9/observatory/getting-started

Connect your first project, instrument an agent, and see traces in Observatory in under 15 minutes.

This guide walks you from an empty Observatory to a live trace flowing in from your first agent. Plan on 10–15 minutes.

## Prerequisites

* An Observatory instance (managed cloud, or [self-hosted](./setup/self-hosted))
* Python 3.12 or newer
* An LLM provider key (OpenAI, Anthropic, Google, or Ollama)
* Permission to create projects in your Observatory organization and workspace

***

## Steps

<Steps>
  <Step title="Create a project">
    Sign in to Observatory and open **Projects**. Click **Add Project**, give it a name, and confirm. Observatory creates the project and an API key in the same step.
  </Step>

  <Step title="Copy your API key">
    On the **Home** page, the API key panel shows the key for the selected organization and workspace. Click **Copy** and store the value as the `FLOWX_OBSERVATORY_API_KEY` environment variable in your app, alongside your organization, workspace, and project IDs.

    ```bash theme={"system"}
    export FLOWX_OBSERVATORY_API_KEY="FX-..."
    export FLOWX_OBSERVATORY_API_URL="https://your-observatory.example.com"
    export FLOWX_OBSERVATORY_ORG_ID="..."
    export FLOWX_OBSERVATORY_WORKSPACE_ID="..."
    export FLOWX_OBSERVATORY_APP_ID="..."
    ```

    <Warning>
      Treat the API key like a database password. Don't commit it to source control.
    </Warning>
  </Step>

  <Step title="Install the SDK">
    Add the SDK to your Python project:

    ```bash theme={"system"}
    pip install flx-observatory-lib
    ```

    The distribution is `flx-observatory-lib`; you import it as `flowxobservatory`. The SDK ships an event queue and a background consumer that batches events to `POST /api/report`. You don't need to manage the connection yourself.
  </Step>

  <Step title="Instrument an agent">
    Decorate the function that runs your agent with `@agent`. The SDK captures inputs, outputs, timings, and any nested chains or tool calls automatically.

    ```python theme={"system"}
    from flowxobservatory import agent

    @agent("claims-approval")
    def run(ctx, payload):
        # your existing logic
        return decide(payload)
    ```

    The string argument names the agent and is what appears in the **Agent** column on the LLM Calls page.

    <Tip>
      Inner LangChain or LangGraph chains are picked up automatically through the `FlowxObservatoryCallbackHandler`. You don't need to instrument them by hand.
    </Tip>
  </Step>

  <Step title="Run the agent and confirm traces">
    Invoke the agent once with realistic input. The SDK flushes events every few seconds.

    Open **Observability** → **Traces** in Observatory. Within \~30 seconds you should see the run, agent name, model, duration, and token count.

    <Check>
      You see a row for your run with status `success`, the right agent name, and a non-zero duration.
    </Check>
  </Step>

  <Step title="Open the trace">
    Click the run. The detail drawer shows the full chain-of-calls — every LLM call, tool invocation, and event with inputs, outputs, latencies, and token usage.
  </Step>
</Steps>

***

## Validate the rest of the platform

Once one trace lands, the rest of Observatory has data to work with:

<CardGroup>
  <Card title="Analytics" icon="chart-line" href="./observability/analytics">
    p50/p95 latency, cost by model, error rate.
  </Card>

  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./governance/risk-dashboard">
    The 6-dimensional risk score updates automatically.
  </Card>

  <Card title="Compliance heatmap" icon="grid" href="./compliance/gap-analysis-heatmap">
    Controls start evaluating against the new evidence.
  </Card>

  <Card title="ROI overview" icon="dollar-sign" href="./roi/overview">
    Configure baselines to start producing ROI numbers.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No traces appear after 30 seconds" icon="circle-question">
    * Confirm `FLOWX_OBSERVATORY_API_KEY` is set in the environment your app actually reads from (not just your shell).
    * Check the app logs for `flowxobservatory` errors — connection refused usually means `FLOWX_OBSERVATORY_API_URL` points at the wrong host or is missing the scheme.
    * Confirm the project you're looking at in the UI matches the API key you exported.
  </Accordion>

  <Accordion title="Traces show but the agent name is empty" icon="circle-question">
    The function must be decorated with `@agent("name")` (not bare `@agent`). The string is what populates the **Agent** column.
  </Accordion>

  <Accordion title="Token counts are zero" icon="circle-question">
    Token counting requires the provider's response metadata. If you're calling a custom or proxied endpoint that strips usage fields, Observatory has nothing to count. See [Event reporting](./sdk/event-reporting) for the rules.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="SDK decorators" icon="at" href="./sdk/decorators">
    Full reference for `@agent`, `@chain`, and `@tool`.
  </Card>

  <Card title="Observability overview" icon="eye" href="./observability/overview">
    What you can do once traces are flowing.
  </Card>
</CardGroup>


# AI Registry
Source: https://docs.flowx.ai/5.9/observatory/governance/ai-registry

Catalogue every model, deployment, and owner across your portfolio — the inventory layer for governance.

The AI Registry is the inventory layer. Before you can govern a portfolio, you need to know what's in it. The registry catalogues models, where they're deployed, who owns them, and what data they touch.

***

## What the registry tracks

| Entity         | Fields                                                           |
| -------------- | ---------------------------------------------------------------- |
| **Model**      | Name, provider, version, modality, capabilities, intended use.   |
| **Deployment** | Environment (dev/stage/prod), endpoint, region, app linkage.     |
| **Owner**      | A user or team. Multiple owners allowed per model.               |
| **Data tags**  | Data classifications the model touches (PII, financial, health). |
| **Risk tier**  | Manual classification or computed from data tags + capability.   |

***

## Why this matters

Governance, compliance, and ROI calculations all need the registry as the inventory of record:

```mermaid theme={"system"}
flowchart LR
    Registry[AI Registry] --> Risk["Risk Dashboard<br/>(data + model risk)"]
    Registry --> Compliance["Compliance<br/>(scope of high-risk apps)"]
    Registry --> ROI["ROI<br/>(per-model cost analysis)"]
    Registry --> Audit["Audit Trail<br/>(ownership for changes)"]
```

If a model isn't in the registry, it doesn't show up in any of the downstream views. The first job of a new Observatory org is usually populating the registry.

***

## Populating the registry

Three ways:

<CardGroup>
  <Card title="From telemetry" icon="wave-pulse">
    Models that show up in runs are auto-registered. You confirm and fill in metadata.
  </Card>

  <Card title="Manual entry" icon="keyboard">
    Add a model that isn't running yet (preview, eval, planned).
  </Card>

  <Card title="Import" icon="file-import">
    Bulk import from CSV or from FlowX AI Platform's agent definitions.
  </Card>

  <Card title="API" icon="code">
    Programmatic registration through `POST /api/registry/models`.
  </Card>
</CardGroup>

***

## Risk tiering

The default tiers map roughly to the EU AI Act risk pyramid:

| Tier             | Examples                                                  |
| ---------------- | --------------------------------------------------------- |
| **Minimal**      | Internal-tool agents, productivity helpers.               |
| **Limited**      | Customer-facing chatbots without consequential decisions. |
| **High**         | Credit decisions, claims approvals, hiring-adjacent.      |
| **Unacceptable** | Banned by regulation — flagged for removal.               |

Tiering can be manual or computed. Computed tiering uses data tags and capability flags (e.g. "makes decisions about people" + "trained on personal data" → High).

***

## API

| Endpoint                         | Use                                 |
| -------------------------------- | ----------------------------------- |
| `GET /api/registry/models`       | List models.                        |
| `POST /api/registry/models`      | Register a model.                   |
| `PUT /api/registry/models/{id}`  | Update metadata.                    |
| `GET /api/registry/deployments`  | List deployments.                   |
| `POST /api/registry/deployments` | Link a model to an environment/app. |

***

## Related resources

<CardGroup>
  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./risk-dashboard">
    Where data and model tags become risk scores.
  </Card>

  <Card title="Compliance" icon="circle-check" href="../compliance/overview">
    Risk tier drives which frameworks apply.
  </Card>
</CardGroup>


# Assessments
Source: https://docs.flowx.ai/5.9/observatory/governance/assessments

Dynamic, weighted-scoring questionnaires for repeatable governance reviews.

Assessments are structured questionnaires you fill in periodically — per app, per release, per audit. Each template scores answers and feeds the result into the [Risk Dashboard](./risk-dashboard) and [Compliance heatmap](../compliance/gap-analysis-heatmap).

***

## Concepts

| Model                  | What it represents                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------- |
| **AssessmentTemplate** | The questionnaire definition. Ordered sections, ordered questions, scoring weights. |
| **Assessment**         | One filled-in (or in-progress) instance of a template, scoped to an app or org.     |

A template renders dynamically: questions can be conditional ("if previous answer was 'yes', show…"). The total score is a weighted sum across answered questions.

***

## Building a template

<Steps>
  <Step title="Open Assessments → Templates">
    Click **New template**.
  </Step>

  <Step title="Add sections">
    Sections group related questions. They render as collapsible blocks when the assessment is taken.
  </Step>

  <Step title="Add questions">
    Each question has: type (yes/no, multi-choice, free-text), weight, and an optional conditional reveal rule.
  </Step>

  <Step title="Define the scoring">
    Map each answer to a numeric value. The template score is sum of (answer value × question weight).
  </Step>

  <Step title="Publish">
    Once published, the template appears under **Take assessment** for everyone in the org.
  </Step>
</Steps>

***

## Taking an assessment

The take-assessment drawer renders the template progressively:

* Conditional questions appear only after their trigger answer is selected
* Progress bar at the top
* Save-as-draft button to leave and resume later
* Submit button only enabled when all required questions are answered

On submit, Observatory computes the score, stores the answers, and surfaces the result on Risk Dashboard and Compliance heatmap.

***

## Use cases

<CardGroup>
  <Card title="Pre-deployment review" icon="rocket">
    Run an "AI release readiness" template against each app before promoting to production.
  </Card>

  <Card title="Quarterly risk review" icon="calendar">
    A "risk review" template per app, scheduled by the GRC team.
  </Card>

  <Card title="Vendor model intake" icon="truck">
    A "third-party model assessment" template that gates onboarding of new providers.
  </Card>

  <Card title="Compliance attestation" icon="clipboard-check">
    Framework-specific templates that produce evidence-ready answers (EU AI Act, NIST RMF).
  </Card>
</CardGroup>

***

## API

| Endpoint                            | Use                                     |
| ----------------------------------- | --------------------------------------- |
| `GET /api/assessments/templates`    | List templates.                         |
| `POST /api/assessments/templates`   | Create.                                 |
| `GET /api/assessments`              | List assessments (draft + submitted).   |
| `POST /api/assessments`             | Start a new assessment from a template. |
| `POST /api/assessments/{id}/submit` | Submit final answers.                   |

***

## Related resources

<CardGroup>
  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./risk-dashboard">
    Assessment scores are one input to the risk score.
  </Card>

  <Card title="Evidence" icon="folder-open" href="./evidence">
    Submitted assessments can be promoted to evidence.
  </Card>
</CardGroup>


# Evidence
Source: https://docs.flowx.ai/5.9/observatory/governance/evidence

Collect, review, and approve evidence for governance controls — automated and manual, with gap analysis.

Evidence is what turns "we have policies" into "we can prove it". Observatory collects evidence automatically where it can (runs, evaluations, alerts) and lets reviewers attach manual artefacts where it can't (sign-offs, screenshots, external reports).

***

## Types of evidence

| Source                             | What it captures                                                      | Collection |
| ---------------------------------- | --------------------------------------------------------------------- | ---------- |
| **Automated — runs**               | A successful or violating run that satisfies (or breaches) a control. | Automatic. |
| **Automated — policy evaluations** | An evaluation result tied to a policy and run.                        | Automatic. |
| **Automated — alert events**       | An alert and its resolution.                                          | Automatic. |
| **Manual — document**              | Uploaded PDFs, screenshots, sign-off forms.                           | Manual.    |
| **Manual — text attestation**      | A reviewer's typed statement.                                         | Manual.    |

***

## Workflow

```mermaid theme={"system"}
flowchart LR
    Source["Source: run, evaluation,<br/>alert, or upload"] --> Draft[Evidence: draft]
    Draft --> Review{Reviewer}
    Review -->|Approve| Approved[Approved]
    Review -->|Reject| Rejected[Rejected with reason]
    Approved --> Mapped[Mapped to controls]
    Rejected --> Discard[Discarded / retried]
```

Every piece of evidence goes through review unless the control is explicitly configured to auto-approve automated sources.

***

## Reviewing evidence

<Steps>
  <Step title="Open Evidence">
    The default view shows everything in the **Draft** state ordered by oldest first.
  </Step>

  <Step title="Inspect the artefact">
    For automated evidence, the run, evaluation, or alert is linked. For manual evidence, the upload is rendered inline.
  </Step>

  <Step title="Pick a control">
    Map the evidence to one or more controls (e.g. an EU AI Act requirement). One artefact can support multiple controls.
  </Step>

  <Step title="Approve or reject">
    Approving moves the artefact into the audit-ready set. Rejecting requires a reason — useful for training the team on what's acceptable.
  </Step>
</Steps>

***

## Gap analysis

The **Gaps** card flags controls that have no approved evidence. Use it to prioritise:

* Sort by framework (EU AI Act, NIST, ISO 42001)
* Sort by severity of the underlying control
* See last-approved-evidence age — anything older than a quarter shows as stale

```http theme={"system"}
GET /api/evidence/gaps?framework=eu-ai-act
```

Returns the controls that lack approved evidence and the time since the last approval.

***

## API

| Endpoint                          | Use                                            |
| --------------------------------- | ---------------------------------------------- |
| `GET /api/evidence`               | List with filters (state, control, framework). |
| `POST /api/evidence`              | Submit manual evidence.                        |
| `POST /api/evidence/{id}/approve` | Approve.                                       |
| `POST /api/evidence/{id}/reject`  | Reject with reason.                            |
| `POST /api/evidence/collect`      | Trigger an automated collection run.           |
| `GET /api/evidence/gaps`          | Gap analysis.                                  |

<Warning>
  Static routes (`/collect`, `/gaps`) are defined before `/{org_id}` in the router. Maintain that order on forks.
</Warning>

***

## Related resources

<CardGroup>
  <Card title="Policies" icon="file-shield" href="./policies">
    Many evidence sources are policy evaluations.
  </Card>

  <Card title="Compliance" icon="circle-check" href="../compliance/overview">
    Where mapped evidence shows up in the heatmap.
  </Card>
</CardGroup>


# Governance
Source: https://docs.flowx.ai/5.9/observatory/governance/overview

Policy engine, risk scoring, evidence collection, and assessments — the controls layer for production AI.

Governance is the layer that turns "we can see what the agent does" into "we know it's allowed to do that". Use it to enforce policies before runs reach users, score risk per app, gather evidence with a review workflow, and run repeatable assessments.

***

## What's inside

<CardGroup>
  <Card title="Policies" icon="file-shield" href="./policies">
    Define and assign governance rules, evaluate them against runs, score compliance.
  </Card>

  <Card title="Evidence" icon="folder-open" href="./evidence">
    Collect, review, and approve evidence — automated or manual.
  </Card>

  <Card title="Assessments" icon="clipboard-check" href="./assessments">
    Dynamic questionnaires with weighted scoring.
  </Card>

  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./risk-dashboard">
    Six-dimensional risk score per app, rolled up to the org.
  </Card>

  <Card title="AI Registry" icon="server" href="./ai-registry">
    Catalogue of models, deployments, and ownership.
  </Card>
</CardGroup>

***

## How governance fits together

```mermaid theme={"system"}
flowchart LR
    Registry["AI Registry<br/>(what we have)"] --> Risk
    Policies["Policies<br/>(what's allowed)"] --> Risk
    Assessments["Assessments<br/>(how we check)"] --> Evidence
    Evidence["Evidence<br/>(proof)"] --> Risk
    Risk["Risk score<br/>(where to focus)"] --> Compliance[Compliance heatmap]
```

The AI Registry is the inventory layer — what exists in your portfolio. Policies and Assessments produce the inputs to risk scoring. Evidence is the artefact layer that proves controls are met. Risk rolls up the four into a single per-app score, and Compliance translates the score into framework-specific status.

***

## When to start where

| Maturity                             | Start with                                                                  |
| ------------------------------------ | --------------------------------------------------------------------------- |
| You just got Observatory running     | [AI Registry](./ai-registry) — catalogue what you have before governing it. |
| You have telemetry but no controls   | [Policies](./policies) — the highest-leverage place to add guardrails.      |
| You have policies but no audit trail | [Evidence](./evidence) — turn enforcement into proof.                       |
| You report to a risk committee       | [Risk Dashboard](./risk-dashboard) — give them one number per app.          |
| You need formal sign-off             | [Assessments](./assessments) — structured, repeatable, scoreable.           |

***

## Related resources

<CardGroup>
  <Card title="Compliance" icon="circle-check" href="../compliance/overview">
    Map controls to EU AI Act, NIST AI RMF, and ISO 42001.
  </Card>

  <Card title="Observability" icon="eye" href="../observability/overview">
    The telemetry that policies and risk scoring read from.
  </Card>
</CardGroup>


# Policies
Source: https://docs.flowx.ai/5.9/observatory/governance/policies

Define, assign, and evaluate governance rules. Bundle rules into packs. Track compliance across apps.

Policies are the rules your runtime has to obey. Observatory's policy engine defines those rules, assigns them to apps, evaluates them against actual runs, and rolls the results up into a compliance score per app and per policy.

***

## Concepts

| Model                | What it represents                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| **Policy**           | A single rule. Carries severity (`low`, `medium`, `high`, `critical`) and an evaluator expression.   |
| **PolicyPack**       | A named bundle of policies that ship together (e.g. "PII basics", "EU AI Act high-risk app").        |
| **PolicyAssignment** | A pack assigned to one app.                                                                          |
| **PolicyEvaluation** | One evaluation of one policy against one run. Stores the outcome and any captured violation context. |

```mermaid theme={"system"}
flowchart LR
    Policy[Policy] --> Pack[PolicyPack]
    Pack --> Assignment[PolicyAssignment]
    App[App] --> Assignment
    Run[Run] --> Eval[PolicyEvaluation]
    Assignment --> Eval
    Policy --> Eval
```

***

## Severities

| Severity     | Use for                                                       | Default behaviour                  |
| ------------ | ------------------------------------------------------------- | ---------------------------------- |
| **critical** | Things that must never happen — PII leak, credential exposure | Page on first violation.           |
| **high**     | Serious deviations from expected behaviour                    | Alert, surfaces on Risk Dashboard. |
| **medium**   | Quality issues — refusals, low confidence                     | Counted, no immediate alert.       |
| **low**      | Style or formatting                                           | Counted only.                      |

***

## Creating a policy

<Steps>
  <Step title="Open Policies → Policies">
    Click **Add policy**.
  </Step>

  <Step title="Name and describe">
    The description is what reviewers see during an audit. Be specific.
  </Step>

  <Step title="Pick a severity">
    Critical and high contribute to the **Compliance** roll-up score; medium and low are reported but don't block.
  </Step>

  <Step title="Define the evaluator">
    Built-in evaluators cover PII detection, toxicity, prompt-injection patterns, and a few model-specific checks. Custom evaluators are user-defined Python predicates.
  </Step>

  <Step title="Test against past runs">
    Use **Evaluate** to dry-run the policy against the last N runs of a chosen app. The preview shows which runs would have violated.
  </Step>
</Steps>

***

## Bundling into packs

Policies travel in packs. A pack is what you assign — never an individual policy.

Typical packs:

* **PII basics** — emails, phone numbers, government IDs.
* **EU AI Act high-risk** — full set of obligations for high-risk apps.
* **Internal data hygiene** — no production data in development environments.
* **Customer-facing assistant** — refusal patterns, escalation triggers.

Create a pack from **Policies → Packs**, add policies to it, then assign the pack to one or more apps under **Assignments**.

***

## Compliance roll-up

The **Compliance** tab scores each app against the policies assigned to it. The score weights by severity — critical violations dominate, low violations contribute proportionally.

```http theme={"system"}
GET /api/policies/compliance?app_id=...
```

Returns:

* `score` — 0–100
* `violations_by_severity`
* `top_violated_policies` — useful for prioritising remediation

***

## API

| Endpoint                         | Use                                    |
| -------------------------------- | -------------------------------------- |
| `GET /api/policies`              | List policies.                         |
| `POST /api/policies`             | Create.                                |
| `GET /api/policies/packs`        | List packs.                            |
| `POST /api/policies/packs`       | Create.                                |
| `POST /api/policies/assignments` | Assign a pack to an app.               |
| `POST /api/policies/evaluate`    | Run evaluation against a run or batch. |
| `GET /api/policies/compliance`   | Roll-up score.                         |

<Warning>
  FastAPI route ordering matters. Static routes (`/evaluate`, `/compliance`) must be defined before the `/{org_id}` catch-all. If you fork the router, keep that order.
</Warning>

***

## Related resources

<CardGroup>
  <Card title="Evidence" icon="folder-open" href="./evidence">
    Capture the artefacts that prove policy enforcement.
  </Card>

  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./risk-dashboard">
    See how policy compliance feeds the per-app risk score.
  </Card>
</CardGroup>


# Risk Dashboard
Source: https://docs.flowx.ai/5.9/observatory/governance/risk-dashboard

Six-dimensional risk scoring per app, rolled up to the org for leadership visibility.

The Risk Dashboard answers one question: where in our AI portfolio should we focus first? Each app gets a score across six dimensions; the dashboard rolls those into a single number per app and an aggregate per org.

***

## The six dimensions

| Dimension            | What it measures                                             |
| -------------------- | ------------------------------------------------------------ |
| **Operational risk** | Error rate, latency stability, drift events.                 |
| **Compliance risk**  | Open compliance gaps weighted by framework severity.         |
| **Policy risk**      | Policy violations weighted by severity.                      |
| **Data risk**        | Sensitivity of data the app handles and exposure.            |
| **Model risk**       | Model maturity, provider concentration, vendor dependencies. |
| **Governance risk**  | Stale assessments, missing evidence, owner gaps.             |

Each dimension scores 0–100. The composite is a weighted average; weights are configurable per org.

***

## How scores update

Scores recompute whenever the inputs change:

```mermaid theme={"system"}
flowchart LR
    Telemetry["Telemetry<br/>(runs, drift, alerts)"] --> Op[Operational]
    Policies[Policy evaluations] --> Pol[Policy]
    Compliance[Compliance evaluations] --> Comp[Compliance]
    Registry["AI Registry<br/>(model, data tags)"] --> Data
    Registry --> Model
    Assessments[Assessments] --> Gov[Governance]
    Evidence[Evidence approvals] --> Gov
    Op & Pol & Comp & Data & Model & Gov --> Composite[Composite score]
```

Telemetry inputs update minute-by-minute. Governance inputs (assessments, evidence) update on submit.

***

## Reading the dashboard

<Steps>
  <Step title="Start at the org roll-up">
    Top card shows the org-wide composite plus distribution across the six dimensions. Spikes are where to look first.
  </Step>

  <Step title="Pick the worst app">
    The app list is sorted by composite score descending. Click the top row.
  </Step>

  <Step title="Inspect the radar">
    The radar chart shows which dimension dominates. A high "Policy risk" with low "Operational risk" means the app runs fine but is breaking rules.
  </Step>

  <Step title="Drill into the inputs">
    Click any dimension to see the underlying records — violating policies, stale evidence, recent drift events.
  </Step>
</Steps>

***

## Weighting the score

Default weights treat every dimension equally. Most orgs override:

| Profile             | Typical weighting                       |
| ------------------- | --------------------------------------- |
| Financial services  | Compliance and policy weighted heavier. |
| Internal-tools team | Operational weighted heavier.           |
| Healthcare          | Data risk weighted heavier.             |

Adjust weights from **Settings → Risk weighting**.

***

## Use cases

<CardGroup>
  <Card title="Where do we invest in remediation?" icon="bullseye">
    The top of the app list is the answer.
  </Card>

  <Card title="Is risk going up or down?" icon="chart-line">
    The trendline on the org card shows 30-day movement.
  </Card>

  <Card title="What does the board see?" icon="briefcase">
    Export the org roll-up to PDF for governance committee packs.
  </Card>

  <Card title="Which apps are audit-ready?" icon="circle-check">
    Sort ascending by **Governance risk** — lowest scores are best documented.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Policies" icon="file-shield" href="./policies">
    Policy compliance feeds the Policy risk dimension.
  </Card>

  <Card title="AI Registry" icon="server" href="./ai-registry">
    The registry's data and model tags feed Data risk and Model risk.
  </Card>
</CardGroup>


# Alerts
Source: https://docs.flowx.ai/5.9/observatory/observability/alerts

Threshold-based alerting with cooldowns and SLA tracking across eight LLM metrics.

Alerts close the loop between observability and action. When a metric breaches the threshold you set, Observatory raises an event, optionally notifies an external system, and tracks SLA against acknowledgement and resolution times.

***

## Anatomy of an alert

```mermaid theme={"system"}
flowchart LR
    Metric[Live metric] --> Rule{"Above<br/>threshold?"}
    Rule -->|Yes| Cooldown{"Inside<br/>cooldown?"}
    Cooldown -->|No| Fire[Create AlertEvent]
    Cooldown -->|Yes| Sleep[Skip]
    Fire --> Notify[Webhook / email]
    Fire --> SLA[Start SLA timer]
```

Two records back this:

* **AlertRule** — the user-defined rule. Metric, operator, threshold, cooldown, notification channel.
* **AlertEvent** — one occurrence of a rule firing. Carries acknowledged-at and resolved-at timestamps.

***

## Supported metrics

| Metric                 | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| **error\_rate**        | Share of errored runs in the window.                         |
| **p50\_latency**       | Median latency in seconds.                                   |
| **p95\_latency**       | 95th-percentile latency in seconds.                          |
| **cost\_per\_hour**    | Aggregated cost across runs in the last hour.                |
| **token\_volume**      | Total tokens in the window.                                  |
| **drift\_composite**   | Composite drift score from [Drift Monitor](./drift-monitor). |
| **policy\_violations** | Count of policy evaluations marked as violated.              |
| **feedback\_negative** | Count of negative feedback events.                           |

***

## Operators

Pick the comparison that matches the metric:

| Operator | Use for                                                               |
| -------- | --------------------------------------------------------------------- |
| `>`      | "Above threshold" — most common, used with latency, error rate, cost. |
| `<`      | "Below threshold" — used with feedback scores, success rate.          |
| `>=`     | Inclusive variants of the above.                                      |
| `<=`     |                                                                       |

***

## Creating a rule

<Steps>
  <Step title="Open Alerts → Rules">
    Click **Add rule**.
  </Step>

  <Step title="Pick a metric and threshold">
    For example, `p95_latency > 8` seconds.
  </Step>

  <Step title="Set the cooldown">
    Default 15 minutes. The same rule won't fire again inside the cooldown window even if the metric stays breached. This is what prevents flapping.
  </Step>

  <Step title="Choose the destination">
    Email, webhook, or both. The webhook payload mirrors the `AlertEvent` shape.
  </Step>

  <Step title="Save and test">
    Use the **Evaluate now** button on the rule row to fire a one-shot evaluation against current data, without touching the cooldown.
  </Step>
</Steps>

***

## API

| Endpoint                               | Use                                      |
| -------------------------------------- | ---------------------------------------- |
| `GET /api/alerts/rules`                | List rules.                              |
| `POST /api/alerts/rules`               | Create a rule.                           |
| `PUT /api/alerts/rules/{id}`           | Update a rule.                           |
| `DELETE /api/alerts/rules/{id}`        | Delete a rule.                           |
| `POST /api/alerts/rules/{id}/evaluate` | One-shot evaluation.                     |
| `GET /api/alerts/events`               | List historical events.                  |
| `POST /api/alerts/events/{id}/ack`     | Acknowledge an event (starts SLA clock). |
| `POST /api/alerts/events/{id}/resolve` | Resolve an event (stops SLA clock).      |

***

## SLA tracking

When an event fires, two timers start: time-to-acknowledge and time-to-resolve. The Alerts page shows current values and historical compliance against the SLA targets you set per rule. Use this to:

* Prove operational readiness to auditors
* Spot rules that fire too often (noise) or never get acknowledged (ignored)

***

## Related resources

<CardGroup>
  <Card title="Drift Monitor" icon="wave-pulse" href="./drift-monitor">
    The source of the `drift_composite` metric.
  </Card>

  <Card title="Audit Trail" icon="clipboard-list" href="../governance/overview">
    Every ack and resolve is captured in the audit log.
  </Card>
</CardGroup>


# Analytics
Source: https://docs.flowx.ai/5.9/observatory/observability/analytics

Cost, latency, error rate, and model performance trends across all your projects.

Analytics aggregates the same telemetry you see in LLM Calls and Traces into trends you can act on at the team or portfolio level. Use it to spend less, not slower agents, and catch regressions across releases.

***

## What you can answer

<CardGroup>
  <Card title="Where is my LLM bill going?" icon="dollar-sign">
    Cost by model and by agent, broken down per day. Drill into the dominant cost driver.
  </Card>

  <Card title="Are my agents getting slower?" icon="stopwatch">
    p50 / p95 / p99 latency over time, per agent and per model.
  </Card>

  <Card title="What's failing and how often?" icon="triangle-exclamation">
    Error rate per model and per agent, with click-through to the failing runs.
  </Card>

  <Card title="Which model is best for this job?" icon="trophy">
    Model performance comparison — cost, latency, and error rate side by side.
  </Card>
</CardGroup>

***

## Key endpoints

These are the analytics API endpoints the UI is built on. You can call them directly to feed BI tools.

| Endpoint                          | Returns                                  |
| --------------------------------- | ---------------------------------------- |
| `GET /api/analytics/usage/costs`  | Daily cost by model and agent.           |
| `GET /api/analytics/usage/models` | Per-model p50, p95, latency, error rate. |
| `GET /api/analytics/usage/agents` | Per-agent volume and cost.               |
| `GET /api/analytics/usage/errors` | Error breakdown by reason and model.     |

Filter parameters mirror the run filters: time range, app, agent, status, model.

***

## Cost tracking

Cost is computed at write time as `tokens × per-1k-token rate` for each LLM call. The rate table lives in `utils/model_costs.py`. Two consequences worth knowing:

* Adding a new model means adding a row to the cost table. Until that happens, calls with that model show `cost = 0`.
* Cost only applies to events of type `llm` — chain or tool spans don't accumulate cost themselves.

<Info>
  The cost column on the `Run` model is denormalised. Any backfill (price change, retroactive rate) requires re-running the cost recalc job.
</Info>

***

## Performance views

The **Model performance** view sorts models on three axes you usually care about together:

* p50 and p95 latency
* Error rate (errors ÷ total)
* Average cost per call

A model that's cheaper but ten times slower is only worth it for batch workloads. The view shows them side by side so the trade-off is visible.

***

## Related resources

<CardGroup>
  <Card title="Drift Monitor" icon="wave-pulse" href="./drift-monitor">
    For distribution-level changes the aggregate charts miss.
  </Card>

  <Card title="Financial ROI" icon="dollar-sign" href="../roi/financial-roi">
    Turn cost and volume into per-agent ROI.
  </Card>
</CardGroup>


# Drift Monitor
Source: https://docs.flowx.ai/5.9/observatory/observability/drift-monitor

Distribution-level monitoring across five metrics, with composite scoring and timeline charts.

Aggregate dashboards catch the obvious. Drift Monitor catches the slow, distributional changes that aggregate charts miss — a small but steady increase in tool-call retries, a quiet shift in response length, a gradually rising refusal rate.

***

## What "drift" means here

Drift Monitor compares the distribution of a metric in a recent window against a baseline distribution. When the shape of the distribution moves enough, it's flagged. The composite drift score combines movement across all five tracked metrics.

```mermaid theme={"system"}
flowchart LR
    Baseline[Baseline window] --> Compare{"Distribution<br/>comparison"}
    Recent[Recent window] --> Compare
    Compare --> Metric[Per-metric score]
    Metric --> Composite[Composite score]
    Composite --> Alert{Above threshold?}
    Alert -->|Yes| Notify[Drift event]
    Alert -->|No| Sleep[No-op]
```

***

## The five metrics

| Metric                         | What it captures                         |
| ------------------------------ | ---------------------------------------- |
| **Latency distribution**       | Wall-clock duration of each call.        |
| **Token-count distribution**   | Total tokens (input + output) per call.  |
| **Cost distribution**          | Cost per call.                           |
| **Error rate**                 | Share of errored calls in the window.    |
| **Output-length distribution** | Character or token count of completions. |

Each contributes to the composite score with a configurable weight.

***

## Running a drift check

Drift snapshots can run on a schedule or be triggered ad hoc through the API.

```http theme={"system"}
POST /api/drift/compute
{
  "app_id": "...",
  "baseline_window": { "days": 30 },
  "recent_window": { "days": 7 }
}
```

Each computation produces a `DriftSnapshot` and one `DriftResult` per metric. The snapshot powers the timeline chart; the per-metric results power the distribution histograms.

***

## Reading the results

<Steps>
  <Step title="Open the timeline">
    The timeline plots the composite score over time. Spikes are the moments worth investigating.
  </Step>

  <Step title="Drill into one snapshot">
    Click a snapshot. The detail view splits the score into the five per-metric contributions.
  </Step>

  <Step title="Compare distributions">
    For each metric, the histogram overlays the baseline and recent distributions so the shift is visible.
  </Step>

  <Step title="Jump to the runs">
    From the snapshot detail, link out to the affected runs in [LLM Calls](./llm-calls) for ground-truth inspection.
  </Step>
</Steps>

***

## When to wire drift in

<CardGroup>
  <Card title="After a model swap" icon="repeat">
    Compare 7 days before vs 7 days after to confirm the new model behaves consistently.
  </Card>

  <Card title="After a prompt change" icon="pen-to-square">
    Use the deployment timestamp as the boundary between baseline and recent.
  </Card>

  <Card title="As a regression backstop" icon="shield-halved">
    Schedule daily drift checks against a 30-day baseline. Spikes flag silent regressions.
  </Card>

  <Card title="Before regulatory reviews" icon="clipboard-check">
    Auditors care about stability. Drift evidence is one of the artefacts they ask for.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Alerts" icon="bell" href="./alerts">
    Trigger alerts when the composite score breaches a threshold.
  </Card>

  <Card title="Compliance heatmap" icon="grid" href="../compliance/gap-analysis-heatmap">
    Drift evidence feeds into the operational-control views.
  </Card>
</CardGroup>


# LLM Calls
Source: https://docs.flowx.ai/5.9/observatory/observability/llm-calls

A searchable, filterable table of every LLM invocation from every project, with full input and output capture.

The LLM Calls page is the single place to find any LLM invocation that has ever passed through Observatory. Use it when you know what you're looking for — a user, an agent, an error spike, a slow call — and you want to drill into the actual prompt and completion.

***

## Key features

<CardGroup>
  <Card title="Lazy-loaded table" icon="table">
    Server-side pagination, sorting, and filtering. The page stays fast on datasets of millions of rows.
  </Card>

  <Card title="Global text search" icon="magnifying-glass">
    The search box runs across agent name, model, input, and output.
  </Card>

  <Card title="Filter by agent" icon="filter">
    Quick filter to scope the table to a single agent name.
  </Card>

  <Card title="Time range" icon="clock">
    Last Hour, 3H, 24H, 7D, 1M, 6M selector at the page header level.
  </Card>

  <Card title="Status badges" icon="circle-check">
    Success, error, in-progress, and timed-out are colour-coded at a glance.
  </Card>

  <Card title="Detail drawer" icon="sidebar">
    Click any row to open the full input, output, metadata, and cost breakdown.
  </Card>
</CardGroup>

***

## Columns

| Column         | What it shows                                                      |
| -------------- | ------------------------------------------------------------------ |
| **Status**     | `success`, `error`, `started`, or timed-out (started > 5 min).     |
| **Start time** | When the call began, in the viewer's local timezone.               |
| **Agent**      | The `@agent("name")` decorator value.                              |
| **Model**      | Provider model identifier — `gpt-4`, `claude-opus-4-7`, etc.       |
| **Duration**   | Wall-clock seconds. Below 4s is success, 4–8s warning, >8s danger. |
| **User**       | The user who triggered the call, when available in event metadata. |
| **Tokens**     | Total tokens for the call (prompt + completion).                   |
| **Requests**   | Number of HTTP requests bundled into the same logical call.        |

***

## Filtering and search

The text search box matches `contains` against the agent name, model, input, and output fields. The agent dropdown is the equivalent of an exact-match filter on the **Agent** column.

For more complex queries — status, model, tags, latency bounds, cost — use the API directly:

```http theme={"system"}
GET /api/run/?status=error&model=gpt-4&min_latency_s=8
```

See [LLMRunsQuery](../sdk/event-reporting#advanced-filtering) for the full parameter list.

***

## The detail drawer

Click any row to open the run detail drawer. It contains:

* The full prompt and completion (rendered as text or JSON depending on payload)
* The chain-of-calls tree if the run contained nested chains or tools — links to [Traces](./traces)
* Token and cost breakdown by model
* Metadata extracted by the SDK (`user_email`, custom tags, request ID)

<Tip>
  Long outputs are virtualised. Use the **Copy** button in the drawer header to grab the full payload when you need to paste it into a bug report.
</Tip>

***

## Common workflows

<AccordionGroup>
  <Accordion title="Find every failed call for one agent in the last 24 hours" icon="circle-question">
    1. Set the time range to **24H**.
    2. Pick the agent from the **Filter by agent** dropdown.
    3. Sort by **Status** to bring errors to the top.
  </Accordion>

  <Accordion title="Find calls slower than 8 seconds" icon="circle-question">
    Sort by **Duration** descending. Rows with the red `danger` badge are above the 8s threshold.
  </Accordion>

  <Accordion title="Find a call by something the user typed" icon="circle-question">
    Paste a snippet of the user's input into the search box. Matching rows surface immediately.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Traces" icon="bars-staggered" href="./traces">
    For runs that contain nested chains and tools, see the trace view.
  </Card>

  <Card title="Analytics" icon="chart-line" href="./analytics">
    Aggregate trends across the same data.
  </Card>
</CardGroup>


# Observability
Source: https://docs.flowx.ai/5.9/observatory/observability/overview

Real-time tracing, analytics, drift detection, and threshold alerts for every LLM call, chain, and tool invocation.

Observability is what tells you what your agents are actually doing. Every run is captured as a chain of events with inputs, outputs, timings, token counts, and cost. From those events you get search, analytics, drift detection, and alerts — without writing any of the plumbing yourself.

## What's inside

<CardGroup>
  <Card title="LLM Calls" icon="bolt" href="./llm-calls">
    Table of every LLM invocation with filters, search, and a detail drawer.
  </Card>

  <Card title="Traces" icon="bars-staggered" href="./traces">
    Full chain-of-calls per run — chains, tools, retries, and durations.
  </Card>

  <Card title="Analytics" icon="chart-line" href="./analytics">
    Cost by model, p50/p95 latency, error rate, and model performance.
  </Card>

  <Card title="Threads" icon="comments" href="./threads">
    Multi-turn conversations grouped from `chat` events.
  </Card>

  <Card title="Drift Monitor" icon="wave-pulse" href="./drift-monitor">
    Distribution monitoring across five metrics with composite scoring.
  </Card>

  <Card title="Alerts" icon="bell" href="./alerts">
    Threshold rules with cooldown, escalation, and SLA tracking.
  </Card>
</CardGroup>

***

## When to use what

| You want to...                                    | Use                              |
| ------------------------------------------------- | -------------------------------- |
| Find a specific run by user, agent, or input text | [LLM Calls](./llm-calls)         |
| Debug why a particular run failed                 | [Traces](./traces)               |
| Track cost and latency over time                  | [Analytics](./analytics)         |
| Inspect a multi-turn conversation                 | [Threads](./threads)             |
| Catch behavioural shifts before users do          | [Drift Monitor](./drift-monitor) |
| Get paged when something breaks                   | [Alerts](./alerts)               |

***

## The data behind the views

Every event the SDK emits lands as one of two records in the database:

* A **Run** — one execution of an agent, chain, or tool. Carries the aggregate cost, duration, status, and saved flag.
* An **Event** — a leaf record inside a run, such as `chain_start`, `tool_end`, `chat`, or `saved`.

The Observability views are all built on top of these two tables. The [SDK reference](../sdk/overview) describes the event flow and how custom events plug in.

***

## Related resources

<CardGroup>
  <Card title="SDK event reporting" icon="paper-plane" href="../sdk/event-reporting">
    How events are batched, sent, and persisted.
  </Card>

  <Card title="Governance" icon="shield" href="../governance/overview">
    Once you can see runs, the next step is shaping them.
  </Card>
</CardGroup>


# Threads
Source: https://docs.flowx.ai/5.9/observatory/observability/threads

Multi-turn conversations grouped from chat events, with per-message latency, cost, and feedback.

Threads group runs that share a conversational context, so you can review a multi-turn dialogue end-to-end instead of jumping between isolated runs.

***

## How threads are built

A thread is constructed from events with name `chat`. The SDK groups consecutive `chat` events that share the same `thread_id` (or, when none is supplied, the same agent and user within a time window).

```python theme={"system"}
from flowxobservatory import track_event

track_event(
    "chat",
    role="user",
    content="What's my policy number?",
    thread_id="cust-42",
)
```

Each emitted `chat` event becomes one `ThreadMessage`. The aggregate `Thread` record carries:

* `started_at`, `ended_at`, `message_count`
* Total tokens and total cost across the thread
* Last message preview for the thread list

***

## What you see per thread

| Field             | Meaning                                     |
| ----------------- | ------------------------------------------- |
| **Thread**        | A short preview of the most recent message. |
| **Agent**         | The agent handling the conversation.        |
| **User**          | The user the conversation belongs to.       |
| **Messages**      | Total number of messages so far.            |
| **Tokens**        | Sum of all message tokens.                  |
| **Cost**          | Sum of cost across all messages.            |
| **Last activity** | When the most recent message landed.        |

***

## Drilling into a thread

Click any thread row to open the full conversation. Each message exposes:

* The full `content`
* Per-message latency
* The associated run, with a link out to the [trace](./traces)
* Any user feedback attached via the feedback API

User feedback collected through the [User Feedback](../governance/overview) flow is rendered inline next to the corresponding assistant message.

***

## Filtering

| Filter            | What it does                                              |
| ----------------- | --------------------------------------------------------- |
| **Agent**         | Scope to one agent.                                       |
| **User**          | Scope to one user.                                        |
| **With feedback** | Show only threads that have at least one feedback record. |
| **Time range**    | Standard time selector.                                   |

***

## Common workflows

<AccordionGroup>
  <Accordion title="Find every conversation a user had with one agent" icon="circle-question">
    Filter by **Agent** and **User**. Threads list returns the matching conversations chronologically.
  </Accordion>

  <Accordion title="Audit a conversation that received negative feedback" icon="circle-question">
    Toggle **With feedback** and sort by **Last activity** descending. Open each thread and inspect the feedback annotation per message.
  </Accordion>

  <Accordion title="See the trace behind a single message" icon="circle-question">
    Open the thread, click the **Run** link next to the message you care about — that opens the trace detail for the underlying run.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Traces" icon="bars-staggered" href="./traces">
    Underlying chain-of-calls per message.
  </Card>

  <Card title="Event reporting" icon="paper-plane" href="../sdk/event-reporting">
    How `chat` events are emitted.
  </Card>
</CardGroup>


# Traces
Source: https://docs.flowx.ai/5.9/observatory/observability/traces

The chain-of-calls view for a single run — every chain, tool call, and event with timings and payloads.

Traces show the hierarchy of work inside one run. Use this view when you need to understand what happened end-to-end — which sub-chain decided to call which tool, how long each step took, and where the request went wrong.

***

## Span hierarchy

A trace is a tree of spans. Each span is one event the SDK reported:

```mermaid theme={"system"}
flowchart TD
    Root[agent_start: claims-approval]
    Root --> C1[chain_start: extract-claim-data]
    C1 --> T1[tool_start: lookup_policy_holder]
    T1 --> T1E[tool_end]
    C1 --> C1E[chain_end]
    Root --> C2[chain_start: assess-risk]
    C2 --> L1[llm_call: gpt-4]
    C2 --> C2E[chain_end]
    Root --> RootE[agent_end]
```

Spans are nested by `parent_run_id`. The first span (root) is the agent call itself. Each chain or tool nested inside gets its own span. Leaf spans are the LLM calls or tool invocations.

***

## What you see per span

| Field              | Meaning                                                                             |
| ------------------ | ----------------------------------------------------------------------------------- |
| **Name**           | Decorator string from `@chain("...")`, `@tool("...")`, or the LangChain class name. |
| **Type**           | `agent`, `chain`, `tool`, `llm`, or a custom event.                                 |
| **Duration**       | Wall-clock milliseconds between `*_start` and `*_end`.                              |
| **Status**         | `success`, `error`, or `in_progress`.                                               |
| **Input / output** | Raw payloads, rendered as text or JSON.                                             |
| **Tokens**         | Per-LLM-call token usage when the provider reports it.                              |
| **Cost**           | Derived from token usage × the model's per-1k-token rate.                           |

***

## Reading a trace

<Steps>
  <Step title="Open the run">
    From [LLM Calls](./llm-calls) or [Threads](./threads), click a row to open the trace detail.
  </Step>

  <Step title="Scan the tree for red">
    Failed spans are highlighted. Their parent chain typically captures the error message in the output.
  </Step>

  <Step title="Inspect the slow spans">
    Sort or eyeball the duration column. A single tool call dominating the duration usually points at the bottleneck.
  </Step>

  <Step title="Open the LLM call">
    Click any `llm` span to see the prompt, system message, and completion alongside token usage.
  </Step>
</Steps>

***

## Comparing two runs

Observatory ships a comparison endpoint that surfaces side-by-side diffs of two runs. From the trace view, click **Compare** and pick a second run. Useful for:

* Investigating a regression after a prompt change
* Comparing the same input across two model versions
* Diffing a passing dataset run against a failing one

```http theme={"system"}
POST /api/run/compare
{ "run_id_a": "...", "run_id_b": "..." }
```

***

## Saved runs

A run is marked **saved** when an event with name `saved` is emitted for it. Saved runs persist beyond retention windows and surface in dataset workflows.

```python theme={"system"}
from flowxobservatory import track_event

track_event("saved", run_id=ctx.run_id)
```

See [Event reporting](../sdk/event-reporting#custom-events) for the full list of custom events.

***

## Related resources

<CardGroup>
  <Card title="LLM Calls" icon="bolt" href="./llm-calls">
    The table view that links into trace detail.
  </Card>

  <Card title="Threads" icon="comments" href="./threads">
    Multi-turn views built on the same trace data.
  </Card>
</CardGroup>


# Observatory
Source: https://docs.flowx.ai/5.9/observatory/overview

Observe, govern, and prove the value of every AI agent running on FlowX from one platform.

FlowX Observatory is the operational layer for AI agents. It turns raw LLM telemetry into the four things you need to run agents in production: visibility, control, regulatory evidence, and a credible ROI story.

## What problem this solves

Generic LLM dashboards stop where the hard work starts. Observatory covers the full path: from the first trace your SDK emits to the EU AI Act control your auditor wants signed off, and the Net Present Value your CFO wants to see.

Reach for Observatory when you need to:

* See exactly what every agent, chain, and tool call did
* Enforce policies before unsafe behaviour reaches users
* Stay continuously aligned with EU AI Act, NIST AI RMF, or ISO 42001
* Quantify the financial impact of AI investments

## The four pillars

<CardGroup>
  <Card title="Observability" icon="eye" href="./observability/overview">
    Real-time tracing, cost and latency analytics, drift detection, and threshold alerts for every LLM call.
  </Card>

  <Card title="Governance" icon="shield" href="./governance/overview">
    Policy engine, risk scoring, evidence collection, and assessments to keep agents accountable.
  </Card>

  <Card title="Compliance" icon="circle-check" href="./compliance/overview">
    EU AI Act, NIST AI RMF, and ISO 42001 controls mapped to your runtime with automated evaluation.
  </Card>

  <Card title="ROI & value" icon="dollar-sign" href="./roi/overview">
    Risk-adjusted financial ROI, payback, NPV, and Monte Carlo sensitivity per agent and per project.
  </Card>
</CardGroup>

***

## How the pieces fit together

```mermaid theme={"system"}
flowchart LR
    subgraph apps [Your apps]
        SDK[Observatory SDK]
    end

    subgraph platform [Observatory platform]
        API[Observatory API]
        DB[("PostgreSQL<br/>+ pgvector")]
        Guards[Observatory Guards]
    end

    subgraph ui [Observatory UI]
        Obs[Observability]
        Gov[Governance]
        Comp[Compliance]
        ROI[ROI & value]
    end

    SDK -->|/api/report| API
    API --> DB
    API -.->|safety checks| Guards
    DB --> Obs
    DB --> Gov
    DB --> Comp
    DB --> ROI
```

The SDK decorates your agents, chains, and tools and streams events to the Observatory API. The API stores telemetry in PostgreSQL with the `pgvector` extension and optionally forwards content through Observatory Guards for safety checks. Every pillar of the UI reads from the same data — what you observe is what you govern, certify, and report on.

***

## Concept glossary

| Term           | What it means in Observatory                                              |
| -------------- | ------------------------------------------------------------------------- |
| **Org**        | The top-level tenant. Owns apps, datasets, prompts, and experiments.      |
| **App**        | A single AI app. Owns runs and API keys.                                  |
| **Run**        | One execution trace of an agent, chain, or tool.                          |
| **Event**      | A log entry inside a run — for example `chain_start`, `tool_end`, `chat`. |
| **Dataset**    | A test set of inputs used for evaluations.                                |
| **Prompt**     | A versioned prompt template.                                              |
| **Experiment** | An evaluation run that scores a prompt or model against a dataset.        |
| **Policy**     | A governance rule evaluated against runs.                                 |
| **Evidence**   | An artefact that proves a control is met.                                 |
| **Risk score** | A six-dimensional score per app.                                          |

***

## Where to go next

<CardGroup>
  <Card title="Getting started" icon="rocket" href="./getting-started">
    Connect your first project and emit your first trace in 15 minutes.
  </Card>

  <Card title="SDK reference" icon="code" href="./sdk/overview">
    Install the SDK and learn the `@agent`, `@chain`, and `@tool` decorators.
  </Card>

  <Card title="Self-hosted setup" icon="wrench" href="./setup/self-hosted">
    Stand up Observatory with Docker Compose for development or on-premise deployments.
  </Card>

  <Card title="AI Platform" icon="hand-sparkles" href="/5.9/ai-platform/ai-in-flowx">
    Build the agents that Observatory observes.
  </Card>
</CardGroup>


# Compliance ROI
Source: https://docs.flowx.ai/5.9/observatory/roi/compliance-roi

Quantify audit-labour savings and risk reduction from automated governance and evidence collection.

Compliance ROI is the half of the AI investment case that usually gets left off the slide. The cost of audits, evidence gathering, and regulatory response is real — and automating it has measurable financial impact.

***

## What this captures

| Component                   | What it measures                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| **Audit labour saved**      | Hours that would have been spent gathering evidence manually, now produced automatically. |
| **Response time reduction** | Time-to-respond to a regulator or auditor, before vs after.                               |
| **Risk mitigation value**   | Expected loss from a compliance failure × probability reduction.                          |
| **Continuous-control cost** | Cost of automated control evaluation — usually small.                                     |

The net is `(audit_saved + risk_mitigation_value) − continuous_control_cost`.

***

## Audit labour saved

For each evidence type, Observatory tracks:

* Number of automated-evidence records produced
* Estimated manual-collection hours that would have been needed
* Loaded hourly rate for the role that would have collected them

Multiplied together, this is the audit-labour saved per period.

Default assumptions (configurable):

| Evidence type                   | Estimated manual hours per record      |
| ------------------------------- | -------------------------------------- |
| Run-based evidence              | 0.10                                   |
| Policy evaluation evidence      | 0.05                                   |
| Alert-event evidence            | 0.25                                   |
| Manual evidence (your reviewer) | Not automated — these still cost time. |

***

## Risk mitigation value

Compliance failures have expected losses. The dashboard estimates two numbers:

* **Expected loss before Observatory** — based on framework severity and your risk-tier mix
* **Expected loss after Observatory** — same calculation with current gap status

The difference is the risk mitigation value attributed to Observatory's compliance work.

<Info>
  Risk mitigation is the most assumption-heavy part of the calculation. Show it alongside the audit-labour number — the latter is closer to ground truth.
</Info>

***

## Where this rolls up

Compliance ROI is one of the inputs to the per-project [Financial ROI](./financial-roi). For projects where compliance work is substantial (banking, insurance, healthcare), it's typically 15–30% of the total ROI case.

***

## Reporting

Two reports executives ask for:

* **Quarterly audit-labour saved** — the audit-hours chart broken out by framework
* **Compliance-risk exposure trend** — month-over-month change in expected loss

Both export to PDF and CSV from **ROI → Compliance**.

***

## Related resources

<CardGroup>
  <Card title="Evidence" icon="folder-open" href="../governance/evidence">
    Where the audit-labour numbers come from.
  </Card>

  <Card title="Compliance" icon="circle-check" href="../compliance/overview">
    The frameworks that frame the risk-mitigation calculation.
  </Card>
</CardGroup>


# Financial ROI
Source: https://docs.flowx.ai/5.9/observatory/roi/financial-roi

Per-agent and per-project payback period, annual ROI %, and 5-year Net Present Value.

Financial ROI is the bottom of the stack — the actual numbers your CFO needs. Per-agent payback, annual ROI %, 5-year Net Present Value, with risk adjustment.

***

## Configuring agent baselines

The ROI calculation hinges on the baseline — what manual effort the agent replaces. Without a baseline, an agent has no measurable upside.

Each agent baseline carries:

| Field                     | Meaning                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------- |
| **Manual hours per case** | How long a human takes to do what the agent now does.                                   |
| **Hourly rate**           | Loaded cost — salary, benefits, overhead.                                               |
| **Volume per month**      | Realistic monthly throughput.                                                           |
| **Replacement ratio**     | 1.0 means the agent fully replaces the human; lower values reflect partial replacement. |

The monthly labour saved is `hours × rate × volume × replacement_ratio`.

***

## The four numbers

| Number              | Formula                                              | What it tells you                             |
| ------------------- | ---------------------------------------------------- | --------------------------------------------- |
| **Monthly savings** | Labour saved − LLM cost − ops overhead               | Run-rate impact.                              |
| **Payback period**  | Implementation cost ÷ monthly savings                | How fast the investment pays for itself.      |
| **Annual ROI %**    | (Annual savings − annual cost) ÷ implementation cost | Percentage return on the up-front investment. |
| **5-year NPV**      | Discounted sum of net cashflows over 5 years         | The standard finance comparison number.       |

Default discount rate is 10% — configurable per org.

***

## Risk adjustment

A favourable headline ROI that ignores compliance risk is a fiction. Observatory adjusts:

```
risk_adjusted_npv = npv × (1 − risk_penalty)
```

The risk penalty is derived from the app's [Risk Dashboard](../governance/risk-dashboard) score. High-risk apps see a meaningful haircut on their NPV; low-risk apps see \~none.

This means an agent with low LLM cost and high compliance gaps may rank below an agent with higher LLM cost but a clean governance posture.

***

## Per-project view

Project-level ROI is the sum of per-agent ROI for agents in the project, with shared implementation costs amortised across them. The project view shows:

* Aggregate payback period
* Per-agent contribution stacked
* Sensitivity bands from [Monte Carlo](./sensitivity-analysis)

***

## Worked example

A claims-approval agent in production:

| Input                 | Value    |
| --------------------- | -------- |
| Manual hours per case | 0.6      |
| Hourly rate           | \$52     |
| Volume / month        | 4,200    |
| Replacement ratio     | 0.85     |
| LLM cost / month      | \$1,180  |
| Implementation cost   | \$48,000 |
| Risk penalty          | 0.08     |

Computed:

* Monthly labour saved: 0.6 × 52 × 4,200 × 0.85 = \$111,384
* Monthly savings: 111,384 − 1,180 = \$110,204
* Payback: 48,000 ÷ 110,204 ≈ **0.4 months**
* Annual ROI %: ≈ **2,650%**
* 5-year NPV (10% discount): ≈ \$5.0M
* Risk-adjusted NPV: ≈ **\$4.6M**

***

## Related resources

<CardGroup>
  <Card title="Compliance ROI" icon="clipboard-check" href="./compliance-roi">
    The audit-savings half of the calculation.
  </Card>

  <Card title="Sensitivity analysis" icon="sliders" href="./sensitivity-analysis">
    Replace point estimates with confidence ranges.
  </Card>
</CardGroup>


# ROI & value
Source: https://docs.flowx.ai/5.9/observatory/roi/overview

Risk-adjusted financial ROI, Value Outcome Units, and Monte Carlo sensitivity — board-grade numbers for AI investment.

ROI & value is the layer that turns telemetry into the kind of numbers a CFO will sign off on. Per-agent, per-project, risk-adjusted, with payback and NPV — and confidence ranges instead of single-point estimates.

***

## What's inside

<CardGroup>
  <Card title="Value Outcome Units" icon="objects-column" href="./value-outcome-units">
    Group agents by business outcome to translate technical metrics into board-level language.
  </Card>

  <Card title="Financial ROI" icon="chart-line" href="./financial-roi">
    Per-agent and per-project ROI: monthly savings, payback, annual ROI %, 5-year NPV.
  </Card>

  <Card title="Compliance ROI" icon="clipboard-check" href="./compliance-roi">
    Quantify audit-labour savings and risk reduction from governance automation.
  </Card>

  <Card title="Sensitivity analysis" icon="sliders" href="./sensitivity-analysis">
    Monte Carlo simulations across ROI inputs — present a range, not a guess.
  </Card>
</CardGroup>

***

## Why this exists

LLM ops dashboards report cost and latency. They don't answer the question executives actually ask: **is this AI investment worth it?**

Observatory's ROI module exists because:

* Per-call cost is meaningless without a baseline ("what would humans cost?")
* A favourable point estimate hides the downside — what if adoption is half what we expected?
* Compliance work has a real cost that needs to live in the same calculation
* "We saved time" is rejected by finance unless it ties to a Value Outcome Unit with revenue or cost attached

***

## The ROI calculation

```mermaid theme={"system"}
flowchart LR
    Baselines["Agent baselines<br/>(hours, rate, volume)"] --> Savings[Labour savings]
    Telemetry["Telemetry<br/>(actual cost, volume)"] --> LLMCost[LLM cost]
    Savings --> Net[Net contribution]
    LLMCost --> Net
    Risk[Compliance risk] -->|adjust| Net
    Net --> Payback[Payback period]
    Net --> NPV[5-year NPV]
    Net --> Monte[Monte Carlo bands]
```

Each agent has a **baseline** — what manual effort it replaces (hours, rate, volume). Observatory combines the baseline with actual telemetry-derived cost to compute net contribution. Compliance risk modifies the contribution. The numbers roll up through Value Outcome Units to per-project ROI.

***

## Where to start

| Maturity                                | Start with                                                        |
| --------------------------------------- | ----------------------------------------------------------------- |
| You have agents but no baselines        | [Financial ROI](./financial-roi) — configure baselines per agent. |
| You have multiple agents per outcome    | [Value Outcome Units](./value-outcome-units) — group them.        |
| You're presenting to executives         | [Sensitivity analysis](./sensitivity-analysis) — show the range.  |
| You're including governance in the case | [Compliance ROI](./compliance-roi) — add audit savings.           |

***

## Related resources

<CardGroup>
  <Card title="AI Registry" icon="server" href="../governance/ai-registry">
    The inventory layer ROI rolls up against.
  </Card>

  <Card title="Analytics" icon="chart-line" href="../observability/analytics">
    Cost telemetry the ROI numbers consume.
  </Card>
</CardGroup>


# Sensitivity analysis
Source: https://docs.flowx.ai/5.9/observatory/roi/sensitivity-analysis

Monte Carlo simulations across ROI inputs to show confidence ranges instead of single-point estimates.

A single ROI number invites a single objection — "what if your adoption number is wrong?" Sensitivity analysis pre-empts that by running thousands of simulations across the input distributions and reporting confidence bands.

***

## What gets simulated

Each ROI input has a distribution, not a point value. The defaults Observatory ships with:

| Input                     | Distribution                 | Why                                                        |
| ------------------------- | ---------------------------- | ---------------------------------------------------------- |
| **Volume**                | Normal, ±20%                 | Adoption typically lands within 20% of forecast.           |
| **Manual hours per case** | Normal, ±15%                 | Real measurements vary; 15% covers the noise.              |
| **LLM cost per call**     | Normal, ±10%                 | Provider pricing and prompt tuning swing it.               |
| **Replacement ratio**     | Beta(α=8, β=2)               | Centred high, with a long tail toward partial replacement. |
| **Discount rate**         | Triangular(0.07, 0.10, 0.13) | Treasury-tied, but uncertain.                              |

You can override any of these per agent or per project.

***

## What the analysis produces

Each Monte Carlo run produces:

* **p10 / p50 / p90** for monthly savings, payback, annual ROI, and NPV
* A **tornado chart** showing which inputs drive the most variance
* A **histogram** of NPV outcomes

The numbers most executives respond to:

* "Base case (p50) NPV is \$4.6M"
* "There's a 90% chance NPV is above \$2.9M"
* "There's a 10% chance NPV is above \$6.1M"

A point estimate of $4.6M is unfalsifiable. A 90% band of $2.9M–\$6.1M is something a board can plan around.

***

## Running an analysis

<Steps>
  <Step title="Open ROI → Sensitivity">
    Pick the project or VOU to analyse.
  </Step>

  <Step title="Confirm or adjust input distributions">
    The defaults are reasonable starting points. For mature deployments with measured variance, tighten them.
  </Step>

  <Step title="Pick the iteration count">
    1,000 iterations is enough for most use cases. 10,000 for board-grade reports. Anything beyond is overkill.
  </Step>

  <Step title="Run">
    Results appear in under a minute. They persist as a `SensitivityRun` so you can compare two analyses side by side.
  </Step>
</Steps>

***

## Reading the tornado

The tornado chart sorts inputs by how much variance they contribute to NPV. Typical result for a mature agent:

1. Volume — usually dominates
2. Replacement ratio — second largest
3. Manual hours per case — meaningful
4. LLM cost — surprisingly small (cost is small vs savings)
5. Discount rate — minor

If volume is the dominant driver and you don't have a tight forecast, that's where to invest measurement effort, not in tuning LLM cost.

***

## When to present this

<CardGroup>
  <Card title="Quarterly business reviews" icon="calendar">
    Pair the p50 with the p10–p90 band. Discuss what's driving the spread.
  </Card>

  <Card title="Investment committee" icon="briefcase">
    A 90% confidence floor that's still positive is the strongest case you can make.
  </Card>

  <Card title="Post-mortems on miss" icon="magnifying-glass">
    When actuals come in below p50, the tornado tells you which assumption was wrong.
  </Card>

  <Card title="Pre-implementation sign-off" icon="signature">
    Show the p10 — if the worst case is unacceptable, scope or delay.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup>
  <Card title="Financial ROI" icon="chart-line" href="./financial-roi">
    The point-estimate calculation sensitivity builds on.
  </Card>

  <Card title="Value Outcome Units" icon="objects-column" href="./value-outcome-units">
    Sensitivity bands also apply at the VOU level.
  </Card>
</CardGroup>


# Value Outcome Units
Source: https://docs.flowx.ai/5.9/observatory/roi/value-outcome-units

Group agents by business outcome so technical metrics translate to board-level revenue and cost language.

A Value Outcome Unit (VOU) is a named business outcome you can attach agents to — Customer Onboarding, Fraud Detection, Claims Processing. Each VOU rolls up the ROI of every agent contributing to it, so the conversation moves from "GPT-4 is expensive" to "Claims Processing nets us \$1.4M a year".

***

## Why VOUs matter

LLM cost dashboards talk about agents. Executives talk about outcomes. VOUs are the bridge.

| Technical view                        | Executive view (VOU)                         |
| ------------------------------------- | -------------------------------------------- |
| "claims-approval p95 is 2.1s"         | "Claims Processing handles 14k cases/month"  |
| "intake-bot costs \$0.07/call"        | "Customer Onboarding saves \$480k/year"      |
| "fraud-classifier error rate is 1.2%" | "Fraud Detection prevented \$2.1M in losses" |

***

## Anatomy of a VOU

| Field              | Meaning                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| **Name**           | Business-readable, e.g. "Claims Processing".                           |
| **Owner**          | The business sponsor (not the engineering owner).                      |
| **Member agents**  | One or many agents that contribute.                                    |
| **Outcome metric** | The KPI the unit moves — cases handled, calls resolved, revenue saved. |
| **Baseline cost**  | What this outcome cost before AI (manual labour, RPA, outsourcing).    |
| **Risk factor**    | A scalar 0.0–1.0 that adjusts net contribution for compliance risk.    |

***

## Setting up a VOU

<Steps>
  <Step title="Open ROI → Value Outcomes">
    Click **New Value Outcome**.
  </Step>

  <Step title="Name and assign an owner">
    Use language the business uses. The owner sees this VOU in their executive view.
  </Step>

  <Step title="Add agents">
    Pick from the registered agents in your AI Registry. One agent can belong to multiple VOUs (e.g. a triage agent feeding both Onboarding and Support).
  </Step>

  <Step title="Define the baseline">
    Specify the manual cost for this outcome — for example, "12 FTE × $65/hr × 1,800 hrs/year" = $1.4M annual baseline.
  </Step>

  <Step title="Set the risk factor">
    Default 1.0 (no adjustment). Reduce for outcomes with significant compliance risk; the dashboard shows risk-adjusted net contribution alongside the raw number.
  </Step>
</Steps>

***

## What the VOU dashboard shows

For each Value Outcome:

* **Labour saved** — derived from baseline minus current ops cost
* **LLM cost** — sum of telemetry-derived cost across member agents
* **Net contribution** — labour saved minus LLM cost
* **Risk-adjusted net contribution** — net × risk factor
* **Volume** — outcome metric over time
* **Top contributing agents** — which agents drive most of the net

***

## Mapping to financial ROI

VOUs are the natural roll-up level for [Financial ROI](./financial-roi). The same payback, NPV, and annual ROI % numbers exist per agent and per VOU; most executive conversations live at the VOU level.

***

## Related resources

<CardGroup>
  <Card title="Financial ROI" icon="chart-line" href="./financial-roi">
    Where VOU contributions become payback and NPV.
  </Card>

  <Card title="Sensitivity analysis" icon="sliders" href="./sensitivity-analysis">
    Show executives the range of outcomes, not just a point estimate.
  </Card>
</CardGroup>


# Decorators
Source: https://docs.flowx.ai/5.9/observatory/sdk/decorators

Reference for the @agent, @chain, and @tool decorators that auto-instrument your code.

Three decorators cover the vast majority of instrumentation needs. Each captures inputs and outputs, measures duration, and emits `*_start` and `*_end` events to Observatory.

***

## `@agent`

The top-level decorator. Wrap the function that handles one user request.

```python theme={"system"}
from flowxobservatory import agent

@agent("claims-approval")
def run(ctx, payload):
    # business logic
    return result
```

### Parameters

<ParamField type="string">
  The agent identifier. Shows up in the **Agent** column on LLM Calls, in Risk Dashboard, and in ROI baselines. Use kebab-case.
</ParamField>

<ParamField type="string">
  Identifier of the user this run belongs to. Surfaces in filters and Threads grouping.
</ParamField>

<ParamField type="dict">
  Arbitrary user properties attached to the run (e.g. `{"plan": "enterprise"}`).
</ParamField>

<ParamField type="list[str]">
  Tags attached to every run of this agent (e.g. `["claims", "prod"]`). Used for filtering in LLM Calls and analytics.
</ParamField>

***

## `@chain`

Use for sub-steps that aren't external work but are worth seeing in the trace.

```python theme={"system"}
from flowxobservatory import chain

@chain("extract-claim-data")
def extract(payload):
    return {"holder": payload["policy_id"], ...}
```

### Parameters

Same shape as `@agent`. The chain inherits the parent run's app and project context — you only need to name it.

<Tip>
  If you're using LangChain or LangGraph, the callback handler creates chain spans automatically. Use `@chain` for handwritten Python that lives between LangChain calls or for non-LangChain frameworks.
</Tip>

***

## `@tool`

Use for the leaf-level units of work — database queries, REST calls, file operations, computation.

```python theme={"system"}
from flowxobservatory import tool

@tool("lookup_policy_holder")
def lookup_policy_holder(policy_id):
    return db.fetch(policy_id)
```

### Parameters

Same signature as `@agent` — `name`, `user_id`, `user_props`, `tags`.

***

## Async functions

All three decorators detect `async def` and wrap it natively. No different syntax.

```python theme={"system"}
@agent("claims-approval")
async def run(ctx, payload):
    data = await extract(payload)
    return await decide(data)
```

***

## Error handling

If the wrapped function raises, the SDK:

1. Emits an `*_end` event with `status=error` and the exception's class and message.
2. Re-raises the exception unchanged.

Your error handling does not need to change. Observatory captures the error context; your `try/except` still runs.

***

## Class-based instrumentation

The decorators also work on methods. Use `@agent` on the entry method of a class:

```python theme={"system"}
class ClaimsAgent:
    @agent("claims-approval")
    def run(self, ctx, payload):
        ...
```

`self` is excluded from captured inputs automatically.

***

## When NOT to use a decorator

| Situation                                           | Better choice                                      |
| --------------------------------------------------- | -------------------------------------------------- |
| You want to attach a custom event (`saved`, `chat`) | Call `track_event()` directly.                     |
| The function runs millions of times per request     | Decorate the parent, not the leaf.                 |
| You only want to record success metrics             | Use the analytics API on the recorded run instead. |

***

## Related resources

<CardGroup>
  <Card title="Event reporting" icon="paper-plane" href="./event-reporting">
    Custom events and the wire protocol.
  </Card>

  <Card title="SDK overview" icon="code" href="./overview">
    Install and configuration.
  </Card>
</CardGroup>


# Event reporting
Source: https://docs.flowx.ai/5.9/observatory/sdk/event-reporting

The event protocol, custom events, and how `saved` and `chat` shape downstream views.

Everything Observatory shows is built on top of a stream of events. The decorators emit them for you, but you can also call `track_event()` directly when you need a custom signal.

***

## The wire protocol

Events are HTTP-POSTed to `/api/report` as a JSON object with an `events` array. Each event is one object:

```json theme={"system"}
{
  "name": "agent_start",
  "app_id": "...",
  "run_id": "...",
  "parent_run_id": null,
  "timestamp": "2026-05-29T08:42:11.123Z",
  "type": "agent",
  "metadata": {"user_email": "..."},
  "input": { ... },
  "output": null
}
```

The API authenticates each request with `Authorization: Bearer <FLOWX_OBSERVATORY_API_KEY>` and resolves `app_id` from the metadata or, failing that, from the project the key belongs to.

***

## Batching

The SDK queues events in memory and a background consumer flushes them on a short interval, posting each batch as `{"events": [...]}` to `/api/report`. On shutdown, the SDK flushes the remaining queue. Delivery is best-effort — if a flush fails, those events are dropped rather than blocking your app.

***

## Cost and token rules

The Observatory API computes cost only for events with `type=llm`. The rules:

1. The event must include `prompt_tokens` and `completion_tokens` (or `total_tokens`).
2. The event must include `model`.
3. There must be a row for the model in the API's model cost table.

Missing any of these → `cost = 0` for that event.

<Warning>
  Adding a new model to your stack requires adding a cost row. Until that happens, the model's calls show up in traces but accumulate zero cost. Run the cost recalc job after editing the table.
</Warning>

***

## Custom events

Three custom events have semantic meaning to Observatory:

### `saved`

Marking a run as **saved** persists it past retention windows and surfaces it for dataset workflows.

```python theme={"system"}
from flowxobservatory import track_event

track_event("saved", run_id=ctx.run_id)
```

Use after a human has signed off on the run — e.g. a reviewer approving a generated document.

### `chat`

A `chat` event represents one message in a conversation. The Threads view groups consecutive `chat` events by `thread_id` into a single thread.

```python theme={"system"}
track_event(
    "chat",
    role="user" or "assistant",
    content="...",
    thread_id="cust-42",
)
```

Without `thread_id`, the SDK falls back to grouping by agent + user within a 30-minute window.

### `feedback`

Attaching feedback to a run or thread message.

```python theme={"system"}
track_event(
    "feedback",
    run_id=ctx.run_id,
    rating="positive" or "negative",
    comment="...",
)
```

Feedback shows up alongside the run in LLM Calls, on the message in Threads, and contributes to the Manage 4.2 NIST control.

***

## Advanced filtering

The runs endpoint accepts the full filter set used by the LLM Calls UI:

```http theme={"system"}
GET /api/run/?app_id=...&status=error&model=gpt-4&min_latency_s=8&tags=high-risk
```

Supported filters:

| Parameter                         | Type          | Notes                            |
| --------------------------------- | ------------- | -------------------------------- |
| `status`                          | enum          | `success` / `error` / `started`. |
| `model`                           | string        | Exact match.                     |
| `agent`                           | string        | Exact match.                     |
| `min_latency_s` / `max_latency_s` | float         | Wall-clock seconds.              |
| `min_cost` / `max_cost`           | float         | USD.                             |
| `tags`                            | list          | Any-of match.                    |
| `user_email`                      | string        | Exact match.                     |
| `from` / `to`                     | ISO timestamp | Inclusive window.                |

***

## Direct API use

If you can't use the Python SDK (different language, edge environment), report events directly:

```bash theme={"system"}
curl -X POST "$FLOWX_OBSERVATORY_API_URL/api/report" \
  -H "Authorization: Bearer $FLOWX_OBSERVATORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "name": "agent_start",
    "type": "agent",
    "run_id": "01HXYZ...",
    "timestamp": "2026-05-29T08:42:11.123Z",
    "input": {"prompt": "..."},
    "metadata": {"agent": "claims-approval"}
  }]}'
```

The shape mirrors the Python SDK's payload exactly.

***

## Related resources

<CardGroup>
  <Card title="Decorators" icon="at" href="./decorators">
    The Python wrappers that emit standard events for you.
  </Card>

  <Card title="Threads" icon="comments" href="../observability/threads">
    Where `chat` events become conversations.
  </Card>
</CardGroup>


# SDK overview
Source: https://docs.flowx.ai/5.9/observatory/sdk/overview

Install the Observatory Python SDK, configure the API key, and learn where instrumentation belongs.

The Observatory SDK is the bridge between your code and the Observatory platform. Decorate your agents, chains, and tools; the SDK captures inputs, outputs, timings, token usage, and cost, then ships events to `/api/report` in the background.

***

## Install

```bash theme={"system"}
pip install flx-observatory-lib
```

The distribution is named `flx-observatory-lib`; the import name is `flowxobservatory`. Optional extras pull in framework integrations — for example `pip install flx-observatory-lib[langchain]` or `flx-observatory-lib[openai]`. Python 3.12 or newer is required.

***

## Configure

Call `configure()` once at startup, or set the equivalent environment variables — the SDK reads them on import.

```python theme={"system"}
from flowxobservatory import configure

configure(
    org_id="your-org-id",
    workspace_id="your-workspace-id",
    project_id="your-project-id",
    api_url="https://your-observatory.example.com",
    api_key="FX-...",
)
```

| Variable                         | Required | Purpose                                                                          |
| -------------------------------- | -------- | -------------------------------------------------------------------------------- |
| `FLOWX_OBSERVATORY_API_KEY`      | Yes      | API key from the Observatory **Home** page (scoped to organization + workspace). |
| `FLOWX_OBSERVATORY_API_URL`      | Yes      | Base URL of your Observatory API.                                                |
| `FLOWX_OBSERVATORY_ORG_ID`       | Yes      | Organization ID.                                                                 |
| `FLOWX_OBSERVATORY_WORKSPACE_ID` | Yes      | Workspace ID.                                                                    |
| `FLOWX_OBSERVATORY_APP_ID`       | Yes      | Project ID (maps to `project_id`).                                               |
| `OBSERVATORY_TRACING`            | No       | Set to `false` to turn off instrumentation without removing decorators.          |

```bash theme={"system"}
export FLOWX_OBSERVATORY_API_KEY="FX-..."
export FLOWX_OBSERVATORY_API_URL="https://your-observatory.example.com"
export FLOWX_OBSERVATORY_ORG_ID="..."
export FLOWX_OBSERVATORY_WORKSPACE_ID="..."
export FLOWX_OBSERVATORY_APP_ID="..."
```

<Warning>
  Don't ship the API key in source control. Use your platform's secret manager.
</Warning>

***

## How the SDK works

```mermaid theme={"system"}
flowchart LR
    Code["Your code<br/>@agent / @chain / @tool"] --> Track[track_event]
    Track --> Queue["Event queue<br/>(in-memory)"]
    Queue --> Consumer["Background consumer<br/>(thread)"]
    Consumer --> API["POST /api/report<br/>(batched)"]
```

* Calls into decorated functions emit `*_start` and `*_end` events through `track_event`.
* The event queue is in-memory and non-blocking — your hot path is not on the critical send path.
* A background consumer flushes batches to `/api/report` on a short interval.
* Delivery is best-effort: if a batch fails to send, those events are dropped rather than blocking your app.

***

## Where instrumentation belongs

| Layer     | Decorator        | When to use                                                    |
| --------- | ---------------- | -------------------------------------------------------------- |
| **Agent** | `@agent("name")` | The top-level function that handles one user request.          |
| **Chain** | `@chain("name")` | A sub-step inside the agent — retrieval, planning, formatting. |
| **Tool**  | `@tool("name")`  | A unit of external work — DB query, REST call, file fetch.     |

Use them like Russian dolls. Each level nests under the previous one, producing the chain-of-calls visible in [Traces](../observability/traces).

```python theme={"system"}
from flowxobservatory import agent, chain, tool

@tool("lookup_policy_holder")
def lookup_policy_holder(policy_id):
    return db.fetch(policy_id)

@chain("extract-claim-data")
def extract(payload):
    holder = lookup_policy_holder(payload["policy_id"])
    return {"holder": holder, "claim": payload["claim"]}

@agent("claims-approval")
def run(ctx, payload):
    data = extract(payload)
    return decide(data)
```

***

## LangChain and LangGraph

The SDK ships a callback handler that auto-captures LangChain's `on_*_start` / `on_*_end` hooks. Register it once and every chain, tool, and LLM call inside the LangChain runtime emits events without further decoration.

```python theme={"system"}
from flowxobservatory.integrations.langchain import FlowxObservatoryCallbackHandler
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(callbacks=[FlowxObservatoryCallbackHandler()])
```

LangGraph nodes are picked up through the same handler.

***

## Where to go next

<CardGroup>
  <Card title="Decorators" icon="at" href="./decorators">
    Full reference for `@agent`, `@chain`, `@tool`.
  </Card>

  <Card title="Event reporting" icon="paper-plane" href="./event-reporting">
    The event protocol, custom events, and `saved` / `chat` semantics.
  </Card>
</CardGroup>


# Environment variables
Source: https://docs.flowx.ai/5.9/observatory/setup/environment-variables

Reference for the environment variables each Observatory service reads.

Each Observatory service reads its configuration from environment variables. This page lists the variables grouped by service. Defaults shown are what the standard Docker Compose stack uses.

***

## Observatory API

### Database

| Environment Variable            | Description               | Default Value         | Component       |
| ------------------------------- | ------------------------- | --------------------- | --------------- |
| `POSTGRES_OBSERVATORY_URI`      | PostgreSQL host and port. | `observatory-db:5432` | observatory-api |
| `POSTGRES_OBSERVATORY_DATABASE` | Database name.            | `observatory`         | observatory-api |
| `POSTGRES_OBSERVATORY_USERNAME` | Database username.        | `observatory`         | observatory-api |
| `POSTGRES_OBSERVATORY_PASSWORD` | Database password.        | `S3cret`              | observatory-api |

### Authentication (Keycloak)

| Environment Variable              | Description                       | Default Value                 | Component       |
| --------------------------------- | --------------------------------- | ----------------------------- | --------------- |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | Base URL of the auth server.      | *(set per env)*               | observatory-api |
| `SECURITY_OAUTH2_REALM`           | Realm name (the organization ID). | *(set per env)*               | observatory-api |
| `SECURITY_OAUTH2_CLIENT_ID`       | OAuth2 client ID.                 | `flowx-platform-authenticate` | observatory-api |
| `SECURITY_OAUTH2_CLIENT_SECRET`   | Client secret.                    | *(set per env)*               | observatory-api |

<Info>
  Observatory authenticates against an external FlowX identity provider — the platform does not bundle its own Keycloak. Point these at your auth server; the realm is your organization ID.
</Info>

### LLM providers

| Environment Variable | Description        | Default Value                       | Component       |
| -------------------- | ------------------ | ----------------------------------- | --------------- |
| `OPENAI_API_KEY`     | OpenAI API key.    | *(required for OpenAI)*             | observatory-api |
| `ANTHROPIC_API_KEY`  | Anthropic API key. | *(optional)*                        | observatory-api |
| `GOOGLE_API_KEY`     | Google API key.    | *(optional)*                        | observatory-api |
| `XAI_API_KEY`        | xAI API key.       | *(optional)*                        | observatory-api |
| `MISTRAL_API_KEY`    | Mistral API key.   | *(optional)*                        | observatory-api |
| `OLLAMA_BASE_URL`    | Local Ollama URL.  | `http://host.docker.internal:11434` | observatory-api |

### Operational

| Environment Variable           | Description                                   | Default Value     | Component       |
| ------------------------------ | --------------------------------------------- | ----------------- | --------------- |
| `URL_PREFIX`                   | Path prefix the API is served under.          | `/ai-observatory` | observatory-api |
| `CACHE_SIZE`                   | In-memory cache size (entries).               | `1000`            | observatory-api |
| `CACHE_TTL`                    | Cache TTL in seconds.                         | `3600`            | observatory-api |
| `GUNICORN_WORKERS`             | Worker processes.                             | `1`               | observatory-api |
| `GUNICORN_TIMEOUT`             | Worker timeout in seconds.                    | `600`             | observatory-api |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of allowed CORS origins. | *(set per env)*   | observatory-api |

***

## Observatory Web

| Environment Variable    | Description                            | Default Value                         | Component       |
| ----------------------- | -------------------------------------- | ------------------------------------- | --------------- |
| `BASE_API_URL`          | Base URL of `observatory-api`.         | `http://localhost:8091`               | observatory-web |
| `PLATFORM_API_URL`      | Base URL of `observatory-platform`.    | `http://localhost:8092`               | observatory-web |
| `KEYCLOAK_ISSUER`       | OIDC issuer URL (auth server + realm). | *(set per env)*                       | observatory-web |
| `KEYCLOAK_REDIRECT_URI` | Post-login redirect.                   | `http://localhost:4900`               | observatory-web |
| `KEYCLOAK_CLIENT_ID`    | Public client ID.                      | `flowx-platform-authenticate`         | observatory-web |
| `KEYCLOAK_SCOPES`       | OAuth2 scopes.                         | `openid profile email offline_access` | observatory-web |

***

## Observatory Platform

| Environment Variable | Description                                   | Default Value   | Component            |
| -------------------- | --------------------------------------------- | --------------- | -------------------- |
| `LOG_LEVEL`          | Logger level.                                 | `INFO`          | observatory-platform |
| `PROMETHEUS_ENABLED` | Toggle Prometheus metrics.                    | `false`         | observatory-platform |
| `ALLOWED_ORIGINS`    | Comma-separated list of allowed CORS origins. | *(set per env)* | observatory-platform |

***

## Observatory SDK

Set these in the environment of the app that uses the SDK — not on the platform itself:

| Environment Variable             | Description                                 | Default Value |
| -------------------------------- | ------------------------------------------- | ------------- |
| `FLOWX_OBSERVATORY_API_KEY`      | API key from the Observatory Home page.     | *(required)*  |
| `FLOWX_OBSERVATORY_API_URL`      | Base URL of the Observatory API.            | *(required)*  |
| `FLOWX_OBSERVATORY_ORG_ID`       | Organization ID.                            | *(required)*  |
| `FLOWX_OBSERVATORY_WORKSPACE_ID` | Workspace ID.                               | *(required)*  |
| `FLOWX_OBSERVATORY_APP_ID`       | Project ID.                                 | *(required)*  |
| `OBSERVATORY_TRACING`            | Set to `false` to turn off instrumentation. | `true`        |

***

## PostgreSQL initialization

The default database setup creates these databases via `init_dbs/multiple-databases.sh` (`POSTGRES_MULTIPLE_DATABASES`):

* `observatory` — the main API store
* `dip`, `writer`, `agent_history`, `builder`, `insights`, `maildb` — companion services in the FlowX AI stack

Default local credentials: `observatory` / `S3cret`. Override via the `POSTGRES_OBSERVATORY_*` env vars in production.

***

## Related resources

<CardGroup>
  <Card title="Self-hosted setup" icon="wrench" href="./self-hosted">
    The Compose flow that consumes these variables.
  </Card>

  <Card title="SDK overview" icon="code" href="../sdk/overview">
    SDK-side environment configuration.
  </Card>
</CardGroup>


# Self-hosted setup
Source: https://docs.flowx.ai/5.9/observatory/setup/self-hosted

Stand up Observatory locally with Docker Compose for development, evaluation, or on-premise deployment.

Observatory ships as a set of containers you can bring up together. This guide is the fastest path from zero to a running platform you can point the SDK at.

***

## Prerequisites

* Docker 24+ and Docker Compose v2
* 8 GB RAM available for containers
* 20 GB disk available for PostgreSQL data
* Network access to the upstream LLM providers you intend to use

The default Compose stack includes:

| Service                | Port | Purpose                                                        |
| ---------------------- | ---- | -------------------------------------------------------------- |
| `observatory-api`      | 8091 | FastAPI backend                                                |
| `observatory-web`      | 4900 | Angular dashboard                                              |
| `observatory-platform` | 8092 | Platform service (organizations, RBAC, Kubernetes integration) |
| `observatory-db`       | 5432 | PostgreSQL with `pgvector`                                     |
| `observatory-docs`     | 4903 | Bundled docs site                                              |

<Info>
  Observatory authenticates against an **external** FlowX identity provider (Keycloak) — it is not bundled in the Compose stack. Point `SECURITY_OAUTH2_*` / `KEYCLOAK_*` at your auth server.
</Info>

***

## Steps

<Steps>
  <Step title="Clone the repo">
    ```bash theme={"system"}
    git clone --recurse-submodules git@github.com:flowx-ai/observatory2.0.git
    cd observatory2.0
    ```

    The submodules carry the API, web, platform, and SDK source. If you forgot `--recurse-submodules`, run:

    ```bash theme={"system"}
    git submodule update --init --recursive
    ```
  </Step>

  <Step title="Create the network">
    The platform expects an external Docker network shared with other FlowX services:

    ```bash theme={"system"}
    docker network create ai-services_node-network 2>/dev/null || true
    ```
  </Step>

  <Step title="Configure the .env file">
    Copy the example and edit the placeholders:

    ```bash theme={"system"}
    cp observatory-api/env.example observatory-api/.env
    ```

    At minimum set `OPENAI_API_KEY` (or your provider equivalent), the `SECURITY_OAUTH2_*` values for your identity provider, and any custom LLM endpoints. See [Environment variables](./environment-variables) for the full table.
  </Step>

  <Step title="Bring up the stack">
    ```bash theme={"system"}
    docker compose up -d --build
    ```

    First start takes a few minutes — the databases initialise and schemas are created.

    <Check>
      `docker compose ps` shows all services in state `Up` or `healthy`.
    </Check>
  </Step>

  <Step title="Confirm the web UI">
    Open [http://localhost:4900](http://localhost:4900). You should see the login page. Sign in with credentials from your FlowX identity provider.
  </Step>

  <Step title="Confirm the API">
    ```bash theme={"system"}
    curl http://localhost:8091/health
    ```

    A `{"status": "ok"}` response means the API is reachable. The `/docs` endpoint serves the OpenAPI explorer.
  </Step>
</Steps>

***

## Rebuilding after code changes

When you edit source code in a submodule, always rebuild — restarting alone won't pick up the changes:

```bash theme={"system"}
docker compose up -d --build
```

<Warning>
  `docker compose restart` does not rebuild images. Always use `up -d --build` after touching service code.
</Warning>

***

## Persistence

The Compose stack persists:

* `pgdata` volume — all telemetry, evidence, runs
* `hf_hub` volume — cached model files

Both survive `docker compose down`. To wipe the platform back to factory state:

```bash theme={"system"}
docker compose down -v
```

***

## Production deployment

The Compose stack is for development and evaluation. For production, see the Kubernetes manifests under `deployment/` and the deployment guide in the repo. Notable production-only concerns:

* Configure persistent volumes for the database
* Set up TLS at the ingress layer
* Point auth at your production identity provider

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Containers start but the UI shows 503" icon="circle-question">
    Most often a missing port name in the service definition. Confirm `observatory-api` is reachable on port 8091 from the `observatory-web` container with `docker compose exec observatory-web curl http://observatory-api:8091/health`.
  </Accordion>

  <Accordion title="Postgres fails to start with 'database does not exist'" icon="circle-question">
    The init script in `init_dbs/multiple-databases.sh` creates the companion databases on first start. If it didn't run, your existing pgdata volume is from an older build. Wipe and start over: `docker compose down -v && docker compose up -d --build`.
  </Accordion>

  <Accordion title="The SDK can't reach the API from outside Docker" icon="circle-question">
    `FLOWX_OBSERVATORY_API_URL` must be `http://localhost:8091` for a host-machine app, not `http://observatory-api:8091` (which only resolves inside the Docker network).
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Environment variables" icon="list" href="./environment-variables">
    Full reference for every env var the platform reads.
  </Card>

  <Card title="Getting started" icon="rocket" href="../getting-started">
    Once the platform is up, instrument your first agent.
  </Card>
</CardGroup>


# FlowX Admin setup
Source: https://docs.flowx.ai/5.9/setup-guides/admin-setup-guide

Complete configuration reference for the FlowX Admin microservice, including logging, databases, Kafka, and various subsystems.

This guide provides a comprehensive reference for configuring the FlowX Admin microservice using environment variables and configuration files.

## Infrastructure prerequisites

Before setting up the Admin microservice, ensure the following components are properly set up:

* **Database Instance**: The Admin microservice connects to the same database as the FlowX.AI Engine.
* **MongoDB**: For additional data management.
* **Redis**: For caching and transient data storage.
* **Kafka**: For audit logs, events, and messaging (if using FlowX.AI Audit functionality).

***

## Core configuration

### Server configuration

| Environment Variable                        | Description                                        | Default Value |
| ------------------------------------------- | -------------------------------------------------- | ------------- |
| `SERVER_PORT`                               | Port on which the Admin service will run           | `8080`        |
| `SPRING_APPLICATION_NAME`                   | Name of the application used for service discovery | `admin`       |
| `SPRING_JACKSON_SERIALIZATION_INDENTOUTPUT` | Enable indented JSON output                        | `true`        |

***

## Database configuration

The Admin microservice connects to the same PostgreSQL or Oracle database as the FlowX.AI Engine for storing process definitions.

| Environment Variable         | Description                      | Default Value                            |
| ---------------------------- | -------------------------------- | ---------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC URL for database connection | `jdbc:postgresql://localhost:5432/flowx` |
| `SPRING_DATASOURCE_USERNAME` | Database username                | `postgres`                               |
| `SPRING_DATASOURCE_PASSWORD` | Database password                | `[your-secure-password]`                 |

<Warning>
  You will need to make sure that the user, password, connection link and database name are configured correctly, otherwise, you will receive errors at start time.
</Warning>

<Info>
  The database schema is managed by a [Liquibase](https://www.liquibase.org/) script provided with the Engine.
</Info>

***

## MongoDB configuration

The Admin microservice also connects to a MongoDB database instance for additional data management.

| Environment Variable                     | Description                                | Default Value                                                                         |
| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `DB_USERNAME`                            | MongoDB username                           | `data-model`                                                                          |
| `DB_PASSWORD`                            | MongoDB password                           | `[your-secure-password]`                                                              |
| `DB_NAME`                                | MongoDB database name                      | `data-model`                                                                          |
| `SPRING_DATA_MONGODB_URI`                | MongoDB connection URI                     | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@localhost:27017/${DB_NAME}?retryWrites=true` |
| `SPRING_DATA_MONGODB_UUIDREPRESENTATION` | UUID representation format                 | `standard`                                                                            |
| `SPRING_DATA_MONGODB_STORAGE`            | Storage type (Azure environments)          | `mongodb` or `cosmosdb`                                                               |
| `MONGOCK_CHANGELOGSSCANPACKAGE_0_`       | Mongock changelog scan package             | `ai.flowx.admin.data.model.config.mongock`                                            |
| `MONGOCK_TRANSACTIONENABLED`             | Enable transactions for Mongock operations | `false`                                                                               |

<Info>
  Ensure that the MongoDB configuration is compatible with the same database requirements as the FlowX.AI Engine, especially if sharing database instances.
</Info>

***

## Redis and caching configuration

Admin Service uses Redis for caching and storing transient data. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

***

## Kafka configuration

The Admin microservice uses Kafka for sending audit logs, managing scheduled timer events, platform component versions, and start timer event updates.

### General Kafka settings

| Environment Variable             | Description                   | Default Value     |
| -------------------------------- | ----------------------------- | ----------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Kafka broker addresses        | `localhost:9092`  |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol             | `PLAINTEXT`       |
| `KAFKA_MESSAGE_MAX_BYTES`        | Maximum message size in bytes | `52428800` (50MB) |

### Kafka producer configuration

| Environment Variable                    | Description            | Default Value                                                 |
| --------------------------------------- | ---------------------- | ------------------------------------------------------------- |
| `SPRING_KAFKA_PRODUCER_KEYSERIALIZER`   | Key serializer class   | `org.apache.kafka.common.serialization.StringSerializer`      |
| `SPRING_KAFKA_PRODUCER_VALUESERIALIZER` | Value serializer class | `org.springframework.kafka.support.serializer.JsonSerializer` |
| `SPRING_KAFKA_PRODUCER_MAXREQUESTSIZE`  | Maximum request size   | `52428800` (50MB)                                             |

### Kafka consumer configuration

| Environment Variable                                        | Description                                             | Default Value                             |
| ----------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------- |
| `KAFKA_CONSUMER_GROUPID_GENERICPROCESSING`                  | Generic processing consumer group                       | `generic-processing-group`                |
| `KAFKA_CONSUMER_THREADS_GENERICPROCESSING`                  | Generic processing threads                              | `6`                                       |
| `KAFKA_CONSUMER_GROUPID_PROCESSSYNC`                        | Process sync consumer group                             | `process-sync-group`                      |
| `KAFKA_CONSUMER_THREADS_PROCESSSYNC`                        | Process sync consumer threads                           | `6`                                       |
| `KAFKA_CONSUMER_GROUPID_BUSINESSRULESYNC`                   | Business rule sync consumer group                       | `business-rule-sync-group`                |
| `KAFKA_CONSUMER_THREADS_BUSINESSRULESYNC`                   | Business rule sync consumer threads                     | `6`                                       |
| `KAFKA_CONSUMER_GROUPID_REUSABLETEMPLATESYNC`               | Reusable template sync consumer group                   | `reusable-template-sync-group`            |
| `KAFKA_CONSUMER_THREADS_REUSABLETEMPLATESYNC`               | Reusable template sync consumer threads                 | `6`                                       |
| `KAFKA_CONSUMER_GROUPID_UIFLOWSYNC`                         | UI flow sync consumer group                             | `ui-flow-sync-group`                      |
| `KAFKA_CONSUMER_THREADS_UIFLOWSYNC`                         | UI flow sync consumer threads                           | `6`                                       |
| `KAFKA_CONSUMER_GROUPID_PROCESSCORRECTIONAFTERAPPOPERATION` | Process correction after app operation consumer group   | `processCorrectionAfterAppOperationGroup` |
| `KAFKA_CONSUMER_THREADS_PROCESSCORRECTIONAFTERAPPOPERATION` | Process correction after app operation consumer threads | `6`                                       |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`                          | Auth exception retry interval (seconds)                 | `10`                                      |

### Topic naming configuration

| Environment Variable             | Description                          | Default Value                                                    |
| -------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
| `DOT`                            | Reference to the primary separator   | `${kafka.topic.naming.separator}`                                |
| `DASH`                           | Reference to the secondary separator | `${kafka.topic.naming.separator2}`                               |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Base package name                    | `ai${dot}flowx${dot}`                                            |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment name                     | ` `                                                              |
| `KAFKA_TOPIC_NAMING_VERSION`     | Topic version                        | `${dot}v1`                                                       |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator                    | `.`                                                              |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator                  | `-`                                                              |
| `KAFKA_TOPIC_NAMING_PREFIX`      | Combined prefix                      | `${kafka.topic.naming.package}${kafka.topic.naming.environment}` |
| `KAFKA_TOPIC_NAMING_SUFFIX`      | Combined suffix                      | `${kafka.topic.naming.version}`                                  |

### Kafka topics configuration

#### Application topics

| Environment Variable                                                      | Description                                        | Pattern                                                                                                                                | Default Value                                                                              |
| ------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `KAFKA_TOPIC_APPLICATION_SYNCRESPONSE`                                    | Sync response topic                                | `${kafka.topic.naming.prefix}application-version.sync.out${kafka.topic.naming.suffix}`                                                 | `ai.flowx.application-version.sync.out.v1`                                                 |
| `KAFKA_TOPIC_APPLICATION_PROCESSSYNC`                                     | Process sync topic                                 | `${kafka.topic.naming.prefix}application-version.sync.process.in${kafka.topic.naming.suffix}`                                          | `ai.flowx.application-version.sync.process.in.v1`                                          |
| `KAFKA_TOPIC_APPLICATION_BUSINESSRULESYNC`                                | Business rule sync topic                           | `${kafka.topic.naming.prefix}application-version.sync.business-rule.in${kafka.topic.naming.suffix}`                                    | `ai.flowx.application-version.sync.business-rule.in.v1`                                    |
| `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATESYNC`                            | Reusable template sync topic                       | `${kafka.topic.naming.prefix}application-version.sync.reusable-template.in${kafka.topic.naming.suffix}`                                | `ai.flowx.application-version.sync.reusable-template.in.v1`                                |
| `KAFKA_TOPIC_APPLICATION_RESOURCEUPDATEPROPAGATION`                       | Resource update propagation topic                  | `${kafka.topic.naming.prefix}application-version.resource.update.propagation${kafka.topic.naming.suffix}`                              | `ai.flowx.application-version.resource.update.propagation.v1`                              |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS`          | Correction after app operation → process request   | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.process.request${kafka.topic.naming.suffix}`           | `ai.flowx.application-version.correction-after-app-operation.process.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE`     | Correction after app operation → business rule     | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.business-rule.request${kafka.topic.naming.suffix}`     | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1`     |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | Correction after app operation → reusable template | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.reusable-template.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_UIFLOW`           | Correction after app operation → UI flow           | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.ui-flow.request${kafka.topic.naming.suffix}`           | `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT`                 | Correction after app operation response topic      | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.response${kafka.topic.naming.suffix}`                  | `ai.flowx.application-version.correction-after-app-operation.response.v1`                  |
| `KAFKA_TOPIC_APPLICATION_UIFLOWSYNC`                                      | UI flow sync topic                                 | `${kafka.topic.naming.prefix}application-version.sync.ui-flow.in${kafka.topic.naming.suffix}`                                          | `ai.flowx.application-version.sync.ui-flow.in.v1`                                          |

#### Audit topics

| Environment Variable    | Description        | Pattern                                                                                          | Default Value                         |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Audit output topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}save${dot}audit${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.save.audit.v1` |

#### Platform Topics

| Environment Variable                         | Description                       | Pattern                                                                                                              | Default Value                                        |
| -------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_PLATFORM_COMPONENTSVERSIONS_IN` | Components versions caching topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}platform${dot}versions${dot}caching${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.platform.versions.caching.v1` |

#### Events gateway topics

| Environment Variable                    | Description                   | Pattern                                                                                                         | Default Value                                        |
| --------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Commands message output topic | `${kafka.topic.naming.prefix}eventsgateway${dot}process${dot}commands${dot}message${kafka.topic.naming.suffix}` | `ai.flowx.eventsgateway.process.commands.message.v1` |

#### Build topics

| Environment Variable                             | Description                      | Pattern                                                                                                                  | Default Value                                     |
| ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA`                  | Build runtime data topic         | `${kafka.topic.naming.prefix}build${dot}runtime-data${kafka.topic.naming.suffix}`                                        | `ai.flowx.build.runtime-data.v1`                  |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_OUT_UPDATES` | Start timer events updates topic | `${kafka.topic.naming.prefix}build${dot}start${dash}timer${dash}events${dot}updates${dot}in${kafka.topic.naming.suffix}` | `ai.flowx.build.start-timer-events.updates.in.v1` |

#### Resource topics

| Environment Variable                  | Description                    | Pattern                                                                                                                      | Default Value                                              |
| ------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Resources usages refresh topic | `${kafka.topic.naming.prefix}application${dash}version${dot}resources${dash}usages${dot}refresh${kafka.topic.naming.suffix}` | `ai.flowx.application-version.resources-usages.refresh.v1` |

### OAuth authentication for Kafka

When using the `kafka-auth` profile, the following variables configure OAuth for Kafka:

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

***

## CAS lib configuration

| Environment Variable  | Description                  | Default Value   |
| --------------------- | ---------------------------- | --------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`       |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`         |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

***

## Logging configuration

The FlowX Admin microservice provides granular control over logging levels for different components:

| Environment Variable | Description                                 | Default Value |   |
| -------------------- | ------------------------------------------- | ------------- | - |
| `LOGGING_LEVEL_ROOT` | Log level for root Spring Boot microservice | `INFO`        |   |
| `LOGGING_LEVEL_APP`  | Log level for application-specific code     | `DEBUG`       |   |

### Changing log levels at runtime

You can adjust log levels dynamically without restarting the service using Spring Boot Actuator endpoints. This is particularly useful for troubleshooting and debugging in production environments.

**Example: Change log level for a specific package**

```bash theme={"system"}
curl 'http://localhost:8081/actuator/loggers/ai.flowx.admin' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
```

**Common logger packages:**

* `ai.flowx.admin` - Application-specific logs
* `org.springframework` - Spring Framework logs
* `org.mongodb.driver` - MongoDB driver logs
* `org.apache.kafka` - Kafka client logs

**Available log levels:**

`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

<Warning>
  Using `DEBUG` or `TRACE` log levels in production may impact performance and generate large log volumes. Revert to `INFO` or `WARN` after troubleshooting is complete.
</Warning>

***

## Localization settings

| Environment Variable           | Description                        | Default Value |
| ------------------------------ | ---------------------------------- | ------------- |
| `APPLICATION_DEFAULTLOCALE`    | Default locale for the application | `en`          |
| `APPLICATION_SUPPORTEDLOCALES` | List of supported locales          | `en, ro`      |

***

## Health monitoring

| Environment Variable                           | Description                              | Default Value                            |
| ---------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| `MANAGEMENT_HEALTH_DB_ENABLED`                 | Enable database health checks            | `true`                                   |
| `MANAGEMENT_HEALTH_KAFKA_ENABLED`              | Enable Kafka health checks               | `true`                                   |
| `MANAGEMENT_SERVER_ADDRESS`                    | Management server bind address           | `0.0.0.0`                                |
| `MANAGEMENT_SERVER_PORT`                       | Management server port                   | `8081`                                   |
| `MANAGEMENT_SERVER_BASEPATH`                   | Base path for management endpoints       | `/manage`                                |
| `MANAGEMENT_SECURITY_ENABLED`                  | Enable security for management endpoints | `false`                                  |
| `MANAGEMENT_ENDPOINTS_WEB_BASEPATH`            | Base path for actuator endpoints         | `/actuator`                              |
| `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE`    | Endpoints to expose                      | `health,info,metrics,prometheus,loggers` |
| `MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED`    | Enable Kubernetes probes                 | `true`                                   |
| `MANAGEMENT_ENDPOINT_HEALTH_SHOWDETAILS`       | Show health check details                | `always`                                 |
| `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` | Enable Prometheus metrics export         | `false`                                  |

### Platform health configuration

| Environment Variable                         | Description                                                                 | Default Value                           |
| -------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------- |
| `FLOWX_PLATFORMHEALTH_NAMESPACE`             | Kubernetes namespace for health checks                                      | `flowx`                                 |
| `FLOWX_PLATFORMHEALTH_MANAGEMENTBASEPATH`    | Base path for management endpoints                                          | `${management.server.base-path}`        |
| `FLOWX_PLATFORMHEALTH_ACTUATORBASEPATH`      | Base path for actuator endpoints                                            | `${management.endpoints.web.base-path}` |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONNAME`        | Kubernetes annotation name for health checks                                | `flowx.ai/health`                       |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONVALUE`       | Kubernetes annotation value for health checks                               | `true`                                  |
| `FLOWX_PLATFORMHEALTH_DISCOVERYINTERVAL`     | Interval at which the platform re-discovers deployed services automatically | `PT5M`                                  |
| `FLOWX_PLATFORMHEALTH_DISCOVERYINITIALDELAY` | Delay before the first automatic service discovery run after startup        | `PT30S`                                 |

***

## Multi-edit and undo/redo configuration

| Environment Variable                    | Description                                     | Default Value |
| --------------------------------------- | ----------------------------------------------- | ------------- |
| `FLOWX_MULTIEDIT_TTL`                   | Time-to-live for multi-edit sessions in seconds | `45`          |
| `FLOWX_UNDOREDO_TTL`                    | Time-to-live for undo/redo actions in seconds   | `86400`       |
| `FLOWX_UNDOREDO_CLEANUP_CRONEXPRESSION` | Cron expression for undo/redo cleanup           | `0 0 2 ? * *` |
| `FLOWX_UNDOREDO_CLEANUP_DAYS`           | Days to keep deleted undo/redo items            | `2`           |

***

## Resources usage configuration

| Environment Variable                                                      | Description                                           | Default Value                             |
| ------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- |
| `FLOWX_LIB_RESOURCESUSAGES_ENABLED`                                       | Enable resources usage tracking                       | `true`                                    |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED`                       | Enable listener for resource usage refreshes          | `true`                                    |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT`         | Thread count for resource usage collector             | `5`                                       |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE`        | Maximum batch size for resource usage collection      | `1000`                                    |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGESREFRESH` | Consumer group ID for resource usage refresh          | `admin-resources-usages-refresh-group`    |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGESREFRESH` | Number of consumer threads for resource usage refresh | `3`                                       |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_TOPIC_RESOURCE_USAGES_REFRESH`           | Kafka topic for resource usage refresh                | `${kafka.topic.resources-usages.refresh}` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_AUTHEXCEPTIONRETRYINTERVAL`              | Retry interval in seconds after auth exceptions       | `3`                                       |

***

## Authentication and Authorization Configuration

The FlowX Admin microservice supports authentication and authorization through OpenID Connect (with Keycloak as the default provider) and allows detailed role-based access control.

### Security type

| Environment Variable                                      | Description                                                           | Default Value                          |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                       |
| `SECURITY_OAUTH2CLIENT`                                   | Enable OAuth2 client                                                  | `enabled`                              |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                 | Service-accounts realm ID                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80`       |

### Service account configuration

The Admin service authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-admin-sa`                                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. The `OPENID_PROVIDER` / `OPENID_KEYCLOAK_*` / `OPENID_ENTRA_*` identity-provider block was also removed from the Admin service in 5.9.0. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

<Info>
  When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.
</Info>

### Designer authentication client

| Environment Variable          | Description                          | Default Value                 |
| ----------------------------- | ------------------------------------ | ----------------------------- |
| `FLOWX_AUTHENTICATE_CLIENTID` | Client ID for authentication service | `flowx-platform-authenticate` |

<Info>
  The role-based access control is configured in the application YAML and grants specific permissions for platform management, user management, process management, integrations management, and configuration management.
</Info>

***

## Ingress and CORS

The Admin service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/`           | `/`              |

The path is set through `services.admin.ingress.admin.path` (or `services.admin.gateway.admin.paths`) in the chart values. Override only if you serve FlowX Admin under a different prefix.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                 | Default Value |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Admin. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

<Warning>
  In production environments, never use the default service account credentials. Always configure secure, environment-specific credentials for authentication.
</Warning>

<Warning>
  Sensitive information such as passwords and client secrets should be managed securely using environment variables or a secrets management solution in production environments.
</Warning>

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Admin service fails to start">
    **Symptoms:** Service crashes on startup or fails health checks.

    **Solutions:**

    1. Verify PostgreSQL connection parameters (`SPRING_DATASOURCE_URL`, credentials) are correct and the database is reachable
    2. Check that MongoDB is running and the connection URI is valid
    3. Ensure Kafka brokers are accessible at the configured `SPRING_KAFKA_BOOTSTRAPSERVERS` address
    4. Review startup logs for specific error messages indicating which dependency is unavailable
  </Accordion>

  <Accordion title="Cannot export or import resources">
    **Symptoms:** Import/export operations fail with permission or authentication errors.

    **Solutions:**

    1. Verify the Keycloak service account has the required roles for import/export operations
    2. Check that `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` and `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` are configured correctly
    3. Ensure the service account has `canImport` access rights in the target workspace
    4. Confirm the target application version is in a WIP state
  </Accordion>

  <Accordion title="Build creation fails">
    **Symptoms:** Creating a build returns errors or times out.

    **Solutions:**

    1. Check connectivity between Admin and the application-manager service
    2. Verify that the Kafka topics for build operations (`KAFKA_TOPIC_BUILD_RUNTIMEDATA`) are created and accessible
    3. Ensure version compatibility between Admin and application-manager services
    4. Review Kafka consumer group lag for build-related topics
  </Accordion>

  <Accordion title="UI not loading in Designer">
    **Symptoms:** Designer interface fails to render or returns blank pages.

    **Solutions:**

    1. Verify the Designer service is running and healthy
    2. Check ingress configuration — ensure the Admin ingress (`admin-admin`) is correctly routing traffic
    3. Review CORS settings in the [Ingress Configuration Guide](./ingress-configuration)
    4. Confirm that the `Fx-Workspace-Id` header is being passed correctly through the ingress
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Configuring an IAM Solution" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup for Keycloak and Microsoft Entra ID
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Ingress Configuration" icon="network-wired" href="./ingress-configuration">
    Centralized ingress guide with CORS configuration and best practices
  </Card>
</CardGroup>


# FlowX Advancing Controller setup
Source: https://docs.flowx.ai/5.9/setup-guides/advancing-controller-setup-guide

This guide provides step-by-step instructions to help you configure and deploy the Advancing Controller effectively.

## Infrastructure prerequisites

Before setting up the Advancing Controller, ensure the following components are properly set up:

* **FlowX.AI Engine Deployment**: The Advancing Controller depends on the FlowX Engine and must be deployed in the same environment. Refer to the FlowX Engine [**setup guide**](./flowx-engine-setup-guide/engine-setup) for more information on setting up the Engine.
* **Database Instance**: The Advancing Controller uses a PostgreSQL or Oracle Database instance as its database.

***

## Dependencies

Ensure the following dependencies are met:

* [Database](#database-configuration): Properly configured database instance.
* [Datasource](#configuring-datasource): Configuration details for connecting to the database.
* [FlowX.AI Engine](./flowx-engine-setup-guide/engine-setup): Must be set up and running. Refer to the FlowX Engine setup guide.

### Database compatibility

The Advancing Controller supports both PostgreSQL and Oracle databases. However, the FlowX.AI Engine and the Advancing Controller must be configured to use the same type of database at any given time. The FlowX.AI Engine employs two databases: one shared with the FlowX.AI Admin microservice for process metadata and instances, and the other dedicated to advancement.

<Warning>
  Mixing PostgreSQL and Oracle Database is not supported; both databases must be of the same type.
</Warning>

***

## Database configuration

### PostgreSQL

A basic PostgreSQL configuration for Advancing.

<Warning>
  If the parallel advancing configuration already exists, you must reset the 'advancing' database by executing the SQL command `DROP DATABASE advancing;`. Once the database has been dropped, the Liquibase script will automatically re-enable it.
</Warning>

***

## Configuration

The Advancing Controller uses a PostgreSQL or an Oracle database as a dependency.

* Ensure that the user, password, connection link, and database name are correctly configured. If these details are not configured correctly, errors will occur at startup.
* The datasource is configured automatically via a Liquibase script inside the engine. All updates will include migration scripts.

### Configuring datasource

If you need to change the datasource configuration detail, you can use the following environment variables:

| Variable                                         | Description                                               | Default Value                                 |
| ------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------- |
| `SPRING_DATASOURCE_URL`                          | JDBC URL for database connection                          | `jdbc:postgresql://postgresql:5432/advancing` |
| `SPRING_DATASOURCE_DRIVERCLASSNAME`              | JDBC driver class name                                    | `org.postgresql.Driver`                       |
| `SPRING_DATASOURCE_USERNAME`                     | Database username                                         | `postgres`                                    |
| `SPRING_DATASOURCE_PASSWORD`                     | Database password                                         | `[your-secure-password]`                      |
| `SPRING_JPA_DATABASE`                            | Database type (accepted values: `oracle` or `postgresql`) | `postgresql`                                  |
| `SPRING_JPA_SHOWSQL`                             | Toggle SQL query logging                                  | `false`                                       |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULT_SCHEMA` | Default database schema (❗️only for Oracle DBs)           | `public`                                      |
| `SPRING_LIQUIBASE_CHANGELOG`                     | Path to Liquibase changelog for database migrations       | `classpath:config/liquibase/master.xml`       |

<Info>
  It's important to keep in mind that the Advancing Controller is tightly integrated with the FlowX.AI Engine. Therefore, it is crucial to ensure that both the Engine and the Advancing Controller are configured correctly and are in sync.
</Info>

***

## Health monitoring

| Variable                       | Description                   | Default Value |
| ------------------------------ | ----------------------------- | ------------- |
| `MANAGEMENT_HEALTH_DB_ENABLED` | Enable database health checks | `true`        |

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Process instances stuck and not advancing">
    **Symptoms:** Process instances remain in a pending state and do not advance to the next node.

    **Solutions:**

    1. Check Kafka connectivity and verify that the Advancing Controller can reach the Kafka brokers
    2. Review the Advancing Controller logs for errors or warnings related to message consumption
    3. Monitor consumer group lag to determine if messages are accumulating without being processed
    4. Verify that the FlowX Engine is running and responsive
  </Accordion>

  <Accordion title="Advancing Controller fails to start">
    **Symptoms:** The service crashes or exits during startup with connection errors.

    **Solutions:**

    1. Verify the PostgreSQL (or Oracle) connection string and credentials are correct
    2. Check that the Kafka broker configuration is valid and the brokers are reachable
    3. Ensure the PostgreSQL (or Oracle) database is accessible and the `advancing` database exists
    4. Review the Liquibase migration logs for schema issues
  </Accordion>

  <Accordion title="Timeout errors during token advancement">
    **Symptoms:** Logs show timeout exceptions when advancing tokens between nodes.

    **Solutions:**

    1. Review process complexity — deeply nested subprocesses or large parallel gateways may require longer timeouts
    2. Monitor Kafka response times to identify broker-side latency
    3. Verify that downstream services responding via Kafka are healthy and not overloaded
  </Accordion>

  <Accordion title="High CPU usage">
    **Symptoms:** The Advancing Controller pod shows consistently high CPU utilization.

    **Solutions:**

    1. Check thread pool settings and reduce concurrency if the system is over-provisioned
    2. Monitor the number of concurrent process instances being advanced
    3. Review Kafka consumer configuration — a high number of partitions with aggressive polling can increase CPU load
    4. Consider scaling horizontally by adding additional replicas
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Advancing Controller" icon="chevron-right" href="../docs/platform-deep-dive/core-components/advancing-controller">
    Learn how the Advancing Controller manages process instance progression
  </Card>

  <Card title="FlowX Engine Setup" icon="gear" href="./flowx-engine-setup-guide/engine-setup">
    Configure the FlowX Engine that the Advancing Controller depends on
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>
</CardGroup>


# Application Manager setup
Source: https://docs.flowx.ai/5.9/setup-guides/application-manager

Set up the Application Manager backend microservice for managing FlowX apps, libraries, versions, manifests, and builds.

The Application Manager is a backend microservice in FlowX.AI that:

✅ Manages FlowX applications, versions, manifests, and configurations.\
✅ Acts as a proxy for front-end resource requests.

## Infrastructure prerequisites

Before you start setting up the Application Manager service, ensure the following infrastructure components are in place:

| Component     | Purpose                    |
| ------------- | -------------------------- |
| PostgreSQL    | Storing application data   |
| MongoDB       | Managing runtime builds    |
| Redis         | Caching needs              |
| Kafka         | Event-driven communication |
| OAuth2 Server | Authentication             |

<Info>
  Ensure that the database for storing application data is properly set up and configured before starting the service.
</Info>

## Dependencies

The Application Manager relies on other FlowX services and components to function properly:

* [**Database configuration**](#database-configuration): For storing application details, manifests, and configurations.
* [**Authorization & Access Management**](#authentication-configuration): For securing access to resources and managing roles.
* [**Kafka Event Bus**](#kafka-configuration): For enabling event-driven operations.
* [**Resource Proxy**](#resource-proxy-configuration): To forward resource-related requests to appropriate services.

## Core configuration environment variables

### Basic service configuration

| Environment Variable         | Description                | Default Value        |
| ---------------------------- | -------------------------- | -------------------- |
| `MULTIPART_MAX_FILE_SIZE`    | Maximum file upload size   | `25MB`               |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum request size       | `25MB`               |
| `LOGGING_CONFIG_FILE`        | Logging configuration file | `logback-spring.xml` |

### Database configuration

#### PostgreSQL configuration

| Environment Variable                | Description         | Default Value                                   |
| ----------------------------------- | ------------------- | ----------------------------------------------- |
| `SPRING_DATASOURCE_URL`             | PostgreSQL JDBC URL | `jdbc:postgresql://postgresql:5432/app_manager` |
| `SPRING_DATASOURCE_USERNAME`        | Database username   | `flowx`                                         |
| `SPRING_DATASOURCE_PASSWORD`        | Database password   | `password`                                      |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class   | `org.postgresql.Driver`                         |

#### MongoDB configuration

The Application Manager requires MongoDB to store runtime build information. Use the following environment variables for configuration:

| Environment Variable          | Description                            | Default Value                                                                                                                                                                  |
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SPRING_DATA_MONGODB_URI`     | MongoDB connection URI                 | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME`                 | MongoDB username                       | `app-runtime`                                                                                                                                                                  |
| `DB_PASSWORD`                 | MongoDB password                       | `password`                                                                                                                                                                     |
| `SPRING_DATA_MONGODB_STORAGE` | Storage type (Azure environments only) | `mongodb` (alternative: `cosmosdb`)                                                                                                                                            |

## Redis configuration

Application Manager uses Redis for caching when required. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

## Kafka configuration

### Kafka connection and security variables

| Environment Variable             | Description            | Default Value                      |
| -------------------------------- | ---------------------- | ---------------------------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Kafka broker addresses | `kafka-flowx-kafka-bootstrap:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol      | `PLAINTEXT`                        |
| `KAFKA_MESSAGE_MAX_BYTES`        | Maximum message size   | `52428800` (50MB)                  |
| `FLOWX_KAFKA_PAYLOADSIZELIMIT`   | Payload size limit     | `512000` (500KB)                   |

### Kafka producer configuration

| Environment Variable                                | Description          | Default Value                                            |
| --------------------------------------------------- | -------------------- | -------------------------------------------------------- |
| `SPRING_KAFKA_PRODUCER_KEYSERIALIZER`               | Key serializer class | `org.apache.kafka.common.serialization.StringSerializer` |
| `SPRING_KAFKA_PRODUCER_PROPERTIES_MAX_REQUEST_SIZE` | Maximum request size | `52428800` (50MB)                                        |

### OAuth authentication variables (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Kafka consumer configuration

| Environment Variable                                                     | Description                                   | Default Value                              |
| ------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------ |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_EXPORT`                     | Application export consumer group             | `app-resource-export-group`                |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_IMPORT`                     | Application import consumer group             | `app-resource-import-group`                |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_USAGES`                     | Resource usages consumer group                | `app-resource-usages-group`                |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATIONRESP` | Resource element validation group             | `app-resource-elem-usage-validation-resp`  |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_COPY`                       | Resource copy consumer group                  | `app-resource-copy-group`                  |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_SYNC`                       | Resource sync consumer group                  | `app-resource-sync-group`                  |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION`          | Resource update propagation consumer group    | `app-resource-update-propagation-group`    |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_CORRECTIONAFTERAPPOPERATION`         | Correction after app operation consumer group | `app-correction-after-app-operation-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_MERGE`                               | Application merge consumer group              | `app-merge-item-group`                     |
| `KAFKA_CONSUMER_GROUPID_BUILD_CREATE`                                    | Build create consumer group                   | `build-create-group`                       |
| `KAFKA_CONSUMER_GROUPID_BUILD_UPDATE`                                    | Build update consumer group                   | `build-update-group`                       |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORT`                           | Build export consumer group                   | `build-resource-export-group`              |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORT`                           | Build import consumer group                   | `build-resource-import-group`              |
| `KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA`                               | Build runtime data consumer group             | `build-runtime-data-group`                 |
| `KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATES`                  | Build timer events updates consumer           | `build-start-timer-events-updates-group`   |
| `KAFKA_CONSUMER_GROUPID_PROCESS_START`                                   | Process start consumer group                  | `process-start-group`                      |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`                                       | Auth exception retry interval (seconds)       | `10`                                       |

### Kafka consumer threads configuration

| Environment Variable                                                     | Description                                     | Default Value |
| ------------------------------------------------------------------------ | ----------------------------------------------- | ------------- |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_EXPORT`                     | Application export consumer threads             | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_IMPORT`                     | Application import consumer threads             | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_USAGES`                     | Resource usages consumer threads                | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATIONRESP` | Resource validation response threads            | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_COPY`                       | Resource copy consumer threads                  | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_SYNC`                       | Resource sync consumer threads                  | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_UPDATEPROPAGATION`                   | Resource update propagation consumer threads    | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_MERGE`                               | Application merge consumer threads              | `3`           |
| `KAFKA_CONSUMER_THREADS_APPLICATION_CORRECTIONAFTERAPPOPERATION`         | Correction after app operation consumer threads | `3`           |
| `KAFKA_CONSUMER_THREADS_BUILD_CREATE`                                    | Build create consumer threads                   | `2`           |
| `KAFKA_CONSUMER_THREADS_BUILD_UPDATE`                                    | Build update consumer threads                   | `4`           |
| `KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA`                               | Build runtime data consumer threads             | `2`           |
| `KAFKA_CONSUMER_THREADS_BUILD_RESOURCE_EXPORT`                           | Build export consumer threads                   | `3`           |
| `KAFKA_CONSUMER_THREADS_BUILD_RESOURCE_IMPORT`                           | Build import consumer threads                   | `3`           |
| `KAFKA_CONSUMER_THREADS_BUILD_STARTTIMEREVENTS_UPDATES`                  | Build timer events updates consumer threads     | `3`           |

### Topic naming convention and pattern creation

The Application Manager uses a sophisticated topic naming convention that follows a structured pattern. This ensures consistency across environments and makes topics easily identifiable.

### Topic naming components

| Component     | Default Value                                                    | Environment Variable             | Description                           |
| ------------- | ---------------------------------------------------------------- | -------------------------------- | ------------------------------------- |
| `package`     | `ai.flowx.`                                                      | `KAFKA_TOPIC_NAMING_PACKAGE`     | Base package identifier               |
| `environment` | ` `                                                              | `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Deployment environment                |
| `version`     | `.v1`                                                            | `KAFKA_TOPIC_NAMING_VERSION`     | Topic version                         |
| `separator`   | `.`                                                              | `KAFKA_TOPIC_NAMING_SEPARATOR`   | Main separator (referred to as `dot`) |
| `separator2`  | `-`                                                              | `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator (as `dash`)       |
| `prefix`      | `${KAFKA_TOPIC_NAMING_PACKAGE}${KAFKA_TOPIC_NAMING_ENVIRONMENT}` | `KAFKA_TOPIC_NAMING_PREFIX`      | Combined `package` and `environment`  |
| `suffix`      | `${KAFKA_TOPIC_NAMING_VERSION}`                                  | `KAFKA_TOPIC_NAMING_SUFFIX`      | The version suffix                    |

### Topic pattern creation

Topics are constructed using the following pattern:

```
{prefix} + service + {separator/dot} + action + {separator/dot} + detail + {suffix}
```

For example, a typical topic might look like:

```
ai.flowx.application-version.export.v1
```

Where:

* `ai.flowx` is the prefix (package + environment)
* `application-version` is the service
* `export` is the action
* `.v1` is the suffix (version)

For more complex topics, additional components are added:

```
ai.flowx.application-version.resources-usages.sub-res-validation.response.v1
```

Where:

* `resources-usages` represents the resource type
* `sub-res-validation` represents the operation type
* `response` indicates it's a response message

### Kafka topic configuration

#### Application resource topics

| Environment Variable                                                                | Description                                                | Default Pattern                                                                            |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_EXPORT`                                           | Application resource export topic                          | `ai.flowx.application-version.export.v1`                                                   |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_IMPORT`                                           | Application resource import topic                          | `ai.flowx.application-version.import.v1`                                                   |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_IN`                                        | Resource usages in topic                                   | `ai.flowx.application-version.resources-usages.operations.bulk.v1`                         |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_OUT`                                       | Resource usages out topic                                  | `ai.flowx.application-version.resources-usages.operations.bulk.v1`                         |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_REFRESH`                                   | Resource usages refresh topic                              | `ai.flowx.application-version.resources-usages.refresh.v1`                                 |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_RESPONSE`                  | Resource element usage validation response                 | `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`             |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_INTEGRATION`           | Resource validation integration topic                      | `ai.flowx.application-version.resources-usages.sub-res-validation.request-integration.v1`  |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_CMS`                   | Resource validation CMS topic                              | `ai.flowx.application-version.resources-usages.sub-res-validation.cms.v1`                  |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_COPY`                                             | Resource copy topic                                        | `ai.flowx.application-version.copy-resource.v1`                                            |
| `KAFKA_TOPIC_APPLICATION_MERGE`                                                     | Application merge topic                                    | `ai.flowx.application-version.merge.v1`                                                    |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN`                   | Correction after app operation response (in)               | `ai.flowx.application-version.correction-after-app-operation.response.v1`                  |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS`          | Correction after app operation → process request           | `ai.flowx.application-version.correction-after-app-operation.process.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE`     | Correction after app operation → business-rule request     | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1`     |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | Correction after app operation → reusable-template request | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_SYSTEM`           | Correction after app operation → system request            | `ai.flowx.application-version.correction-after-app-operation.system.request.v1`            |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_WORKFLOW`         | Correction after app operation → workflow request          | `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1`          |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_UIFLOW`           | Correction after app operation → UI flow request           | `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS`                                 | Sync → process (in)                                        | `ai.flowx.application-version.sync.process.in.v1`                                          |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE`                            | Sync → business-rule (in)                                  | `ai.flowx.application-version.sync.business-rule.in.v1`                                    |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE`                        | Sync → reusable-template (in)                              | `ai.flowx.application-version.sync.reusable-template.in.v1`                                |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_SYSTEM`                                  | Sync → system (in)                                         | `ai.flowx.application-version.sync.system.in.v1`                                           |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_WORKFLOW`                                | Sync → workflow (in)                                       | `ai.flowx.application-version.sync.workflow.in.v1`                                         |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_UIFLOW`                                  | Sync → UI flow (in)                                        | `ai.flowx.application-version.sync.ui-flow.in.v1`                                          |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN`                                          | Sync in (general response channel)                         | `ai.flowx.application-version.sync.out.v1`                                                 |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION`                                | Resource update propagation                                | `ai.flowx.application-version.resource.update.propagation.v1`                              |

#### Build resource topics

| Environment Variable                            | Description                | Default Pattern                                   |
| ----------------------------------------------- | -------------------------- | ------------------------------------------------- |
| `KAFKA_TOPIC_BUILD_UPDATE`                      | Build update topic         | `ai.flowx.build.update.v1`                        |
| `KAFKA_TOPIC_BUILD_CREATE`                      | Build create topic         | `ai.flowx.build.create.v1`                        |
| `KAFKA_TOPIC_BUILD_RESOURCE_EXPORT`             | Build export topic         | `ai.flowx.build.export.v1`                        |
| `KAFKA_TOPIC_BUILD_RESOURCE_IMPORT`             | Build import topic         | `ai.flowx.build.import.v1`                        |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATES` | Timer events updates topic | `ai.flowx.build.start-timer-events.updates.in.v1` |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA`                 | Build runtime data topic   | `ai.flowx.build.runtime-data.v1`                  |

#### Process topics

| Environment Variable                                | Description                     | Default Pattern                                                     |
| --------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`              | Process start for event topic   | `ai.flowx.core.trigger.start-for-event.process.v1`                  |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN`                | Process start by name topic     | `ai.flowx.core.trigger.start-by-name.process.v1`                    |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT`               | Process start by name out topic | `ai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET`  | Set timer schedule topic        | `ai.flowx.core.trigger.set.timer-event-schedule.v1`                 |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Stop timer schedule topic       | `ai.flowx.core.trigger.stop.timer-event-schedule.v1`                |

#### Other topics

| Environment Variable                    | Description                                                                                                   | Default Pattern                                  |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `KAFKA_TOPIC_AUDIT_OUT`                 | Audit topic                                                                                                   | `ai.flowx.core.trigger.save.audit.v1`            |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Events gateway messages topic                                                                                 | `ai.flowx.eventsgateway.receive.copyresource.v1` |
| `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT`   | Topic for publishing runtime config-param change events to the process engine (available from FlowX.AI 5.9.1) | `ai.flowx.config.params.events.v1`               |

<Info>
  These Kafka topics use predefined naming conventions for ease of use. Optional adjustments may be made if the desired topic name cannot be achieved with the standard structure.
</Info>

## Authentication configuration

### Security type

| Environment Variable                                      | Description                                                           | Default Value                          |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                       |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                 | Service-accounts realm ID                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80`       |

### Service account configuration

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-runtime-manager-sa`                                                                         |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Info>
  The Application Manager and the Runtime Manager are built from the same artifact and share the `flowx-runtime-manager-sa` service account, which is why the default client ID here is not `flowx-application-manager-sa`.
</Info>

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

Refer to the dedicated section for configuring user roles and access rights:

<Card title="Access Management" href="./access-management/access-management-overview" icon="lock" />

## File storage configuration

<Info>
  S3 is used in the Application Manager for:

  * Storing imported and exported resources
  * Storing application versions and builds that are imported or exported
</Info>

| Environment Variable                           | Description            | Default Value                              | Default               |
| ---------------------------------------------- | ---------------------- | ------------------------------------------ | --------------------- |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`         | S3 server URL          | `http://minio:9000`                        | None                  |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY`         | S3 access key          | `Ha0wvtOE9gQ2NSzghEcs`                     | None                  |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY`         | S3 secret key          | `jY7nYLVtNh9JzMflliQKu3noPpjxD3prxIkliErX` | None                  |
| `APPLICATION_FILESTORAGE_TYPE`                 | Storage type           | `s3`                                       | `s3`                  |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY`     | File deletion strategy | `delete`                                   | `delete`              |
| `APPLICATION_FILESTORAGE_S3_ENABLED`           | Enable S3 storage      | `true`                                     | `true`                |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable S3 encryption   | `false`                                    | `false`               |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`      | S3 bucket name prefix  | `applications-bucket`                      | `applications-bucket` |

## Monitoring and health check configuration

| Environment Variable                                 | Description             | Default Value                                                                   | Default |
| ---------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- | ------- |
| `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED`       | Prometheus metrics      | `false`                                                                         | `false` |
| `MANAGEMENT_HEALTH_KUBERNETES_ENABLED`               | Kubernetes health check | `false`                                                                         | `true`  |
| `MANAGEMENT_HEALTH_REDIS_ENABLED`                    | Redis health check      | `false`                                                                         | `true`  |
| `MANAGEMENT_HEALTH_KAFKA_ENABLED`                    | Kafka health check      | `true`                                                                          | `true`  |
| `MANAGEMENT_HEALTH_LIVENESSSTATE_ENABLED`            | Liveness state          | `true`                                                                          | `false` |
| `MANAGEMENT_HEALTH_READINESSSTATE_ENABLED`           | Readiness state         | `true`                                                                          | `false` |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDE`  | Liveness probes         | `ping,diskSpace,accessInfo,buildInfo,db,mongo,kafkaClusterHealthCheckIndicator` | `ping`  |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE` | Readiness probes        | `ping,diskSpace,accessInfo,buildInfo`                                           | `ping`  |

## Resource proxy configuration

The Resource Proxy module forwards resource-related requests to appropriate services, handling CRUD operations on the manifest. It requires proper configuration of proxy endpoints:

| Environment Variable                                    | Description                        | Default Value    | Default   |
| ------------------------------------------------------- | ---------------------------------- | ---------------- | --------- |
| `RESOURCE_PROXY_MANIFEST_URL`                           | Manifest URL for resource proxy    | URL value        | None      |
| `RESOURCE_PROXY_TARGET_URL`                             | Target URL for resource forwarding | URL value        | None      |
| `FLOWX_RESOURCEPROXY_RETRYGETRESOURCETIMEOUTMS`         | Resource retrieval timeout         | `500`            | `500`     |
| `FLOWX_RESOURCEPROXY_RETRYGETRESOURCEMAXCOUNT`          | Maximum resource retrieval retries | `10`             | `10`      |
| `FLOWX_RESOURCEPROXY_WEBCLIENT_RETRYATTEMPTS`           | Web client retry attempts          | `2`              | `2`       |
| `FLOWX_RESOURCEPROXY_WEBCLIENT_RETRYBACKOFF`            | Retry backoff time (seconds)       | `1`              | `1`       |
| `FLOWX_RESOURCEPROXY_WEBCLIENT_MAXINMEMORYSIZE`         | Maximum in-memory size             | `5MB`            | `5MB`     |
| `FLOWX_RUNTIMEEXECUTIONPROXY_WEBCLIENT_MAXINMEMORYSIZE` | Maximum REST request size          | `5242880` (5 MB) | `5242880` |

<Info>
  `FLOWX_RUNTIMEEXECUTIONPROXY_WEBCLIENT_MAXINMEMORYSIZE` - Specifies the maximum size (in bytes) of in-memory data for REST requests. This is particularly useful when dealing with large payloads to prevent excessive memory consumption.

  * Default Value: 5242880 (5 MB)
  * Usage Example: Set to 10485760 (10 MB) to allow larger in-memory request sizes.
</Info>

## Proxy connection merge configuration

Configuration for how proxy connection resources are handled during application merges (import, export, conflict resolution).

| Environment Variable                                                            | Description                                                  | Default Value                      |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------- |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_RESOURCEIDFIELD`              | Resource ID field for proxy connection merge                 | `resourceId`                       |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_FLATTENMAP_IDFIELDS`          | Flatten map ID fields for proxy connection merge             | `resourceId, name`                 |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_FLATTENMAP_EXCLUDEDJSONPATHS` | Excluded JSON paths for proxy connection flatten map         | `authorization.configuration`      |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_COMPARE_REMOVEDJSONPATHS`     | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_CONFLICT_EXCLUDEDJSONPATHS`   | Excluded JSON paths for proxy connection conflict detection  | `resourceId, resourceDefinitionId` |

***

## Scheduler configuration

The Application Manager scheduler supports retrying failed deployments:

| Environment Variable                         | Description                  | Default Value |
| -------------------------------------------- | ---------------------------- | ------------- |
| `FLOWX_SCHEDULER_RETRYFAILEDDEPLOYMENTSCRON` | Failed deployment retry cron | `0 * * * * *` |

### Retry failed deployments

Configures a cron job to retry updating builds in the runtime database every minute when previous attempts have failed.

## Configuring logging

To control the logging levels for the Application Manager, use the following environment variables:

| Environment Variable | Description                     | Default Value |
| -------------------- | ------------------------------- | ------------- |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot logs level     | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-level logs level    | `INFO`        |
| `LOGGING_LEVEL_DB`   | Database interactions log level | `INFO`        |

## CAS lib configuration

| Environment Variable  | Description                  | Default Value   |
| --------------------- | ---------------------------- | --------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`       |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`         |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

## Data model overview

The Application Manager stores application data using a relational database schema, with key entities such as application, application\_version, and application\_manifest. Below are descriptions of primary entities:

* **Application** - Defines an application with its details like name, type, and metadata.
* **Application Branch** - Represents branches for versioning within an application.
* **Application Version** - Keeps track of each version of an application, including committed and WIP statuses.
* **Application Manifest** - Contains the list of resources associated with a specific application version.

## Ingress and CORS

The Application Manager service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/appmanager` | `/`              |

The path is set through `services.application-manager.ingress.admin.path` (or `services.application-manager.gateway.admin.paths`) in the chart values. The chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` by default to allow larger application-manifest uploads — adjust the annotation if you need a different limit.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                               | Default Value |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Application Manager. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).


# Authorization system setup
Source: https://docs.flowx.ai/5.9/setup-guides/authorization-setup-guide

Configure these environment variables for the authorization-system microservice deployment.

The authorization-system microservice provides centralized authorization services for the FlowX.AI platform, managing workspaces, users, groups, roles, and permissions. It works alongside SpiceDB to deliver fine-grained access control and supports the  Workspaces feature.

## Database configuration

<Warning>
  The authorization-system **must** use a dedicated PostgreSQL database. Do not share with other FlowX.AI services.
</Warning>

```bash Environment Variables theme={"system"}
SPRING_DATASOURCE_URL=jdbc:postgresql://postgresql:5432/authorization_system
SPRING_DATASOURCE_USERNAME=flowx
SPRING_DATASOURCE_PASSWORD=<password>  # Use Kubernetes Secret
```

**Requirements:**

* Database user needs full access to `authorization_system` database
* PostgreSQL must be available before service startup

## CAS client library configuration

<Info>
  The authorization-system uses the CAS client library to communicate with SpiceDB for ACL operations.
</Info>

```bash Environment Variables theme={"system"}
FLOWX_SPICEDB_HOST=spicedb
FLOWX_SPICEDB_PORT=50051
FLOWX_SPICEDB_TOKEN=<spicedb-token>  # Use Kubernetes Secret
```

<Tip>
  The SpiceDB token must match the `preshared_key` value from the [SpiceDB Kubernetes secret](./spicedb#step-3-create-kubernetes-secret). This same value is used as:

  * `preshared_key` in the SpiceDB Kubernetes secret
  * `SPICEDB_GRPC_PRESHARED_KEY` for SpiceDB configuration
  * `FLOWX_SPICEDB_TOKEN` for FlowX services
</Tip>

**Configuration Parameters:**

* **SpiceDB Host**: Service hostname (typically `spicedb`)
* **SpiceDB Port**: gRPC port (standard: `50051`)
* **SpiceDB Token**: Authentication token for SpiceDB access

### Runtime authorization backend

Selects which backend the CAS client library uses for runtime authorization checks. With `CUSTOM` (the default), authorization requests are served by the authorization-system service over REST. With `SPICEDB`, checks are delegated directly to SpiceDB. The value is defined once in the shared CAS client library and inherited by every service; override it only if instructed by FlowX.

| Environment Variable                                            | Description                                                                                                                               | Default Value |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION`                    | Runtime authorization backend. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB.                       | `CUSTOM`      |
| `FLOWX_LIB_CASCLIENT_CACHE_WORKSPACEVALIDATION_LOCALTTLSECONDS` | Local cache TTL (seconds) for workspace-validation results in the CAS client library. Shared by every service that embeds the CAS client. | `3600`        |

## OAuth2/Keycloak configuration

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server (internal)                                                                                                            | -                                                                                                  |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-authorization-system-sa`                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       | -                                                                                                  |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               | -                                                                                                  |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Token endpoint, resolved against the service-accounts realm                                                                                           | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

***

## Redis configuration

Authorization System uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

## Kafka configuration

### Connection settings

| Environment Variable               | Description                                  | Default Value      |
| ---------------------------------- | -------------------------------------------- | ------------------ |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`    | Kafka broker addresses                       | `localhost:9092`   |
| `SPRING_KAFKA_SECURITY_PROTOCOL`   | Security protocol for Kafka                  | `PLAINTEXT`        |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size                         | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions (seconds) | `10`               |

### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

### Audit topic

| Environment Variable    | Description                  | Default Value                         |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Organization events topic

| Environment Variable                  | Description                             | Default Value                     |
| ------------------------------------- | --------------------------------------- | --------------------------------- |
| `KAFKA_TOPIC_ORGANIZATION_EVENTS_OUT` | Topic for organization lifecycle events | `ai.flowx.organization.events.v1` |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

## Service account realm secrets

These variables configure the client secrets for service accounts in the dedicated service accounts realm. Liquibase uses these secrets when provisioning the SA realm during deployment.

By default, secrets are left empty and auto-generated. Set explicit values only if you need to reference specific service account credentials in custom integrations.

| Environment Variable                                                | Description                                                  | Default Value  |
| ------------------------------------------------------------------- | ------------------------------------------------------------ | -------------- |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXORGANIZATIONMANAGERSA`  | Client secret for the organization-manager service account   | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXADMINSA`                | Client secret for the admin service account                  | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXAUTHORIZATIONSYSTEMSA`  | Client secret for the authorization-system service account   | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXINTEGRATIONDESIGNERSA`  | Client secret for the integration-designer service account   | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXPROCESSENGINESA`        | Client secret for the process-engine service account         | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXRUNTIMEMANAGERSA`       | Client secret for the runtime-manager service account        | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXSCHEDULERCORESA`        | Client secret for the scheduler-core service account         | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXTASKMANAGEMENTPLUGINSA` | Client secret for the task-management-plugin service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXLICENSESA`              | Client secret for the license service account                | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXEMAILGATEWAYSA`         | Client secret for the email-gateway service account          | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXWEBHOOKGATEWAYSA`       | Client secret for the webhook-gateway service account        | Auto-generated |

***

## Management

```bash Environment Variables theme={"system"}
MANAGEMENT_SERVER_PORT=8081
```

## Organization admin bootstrap

<Warning>
  The authorization-system uses a fallback mechanism to create the first organization administrator when no admin users exist.
</Warning>

### Primary method (recommended)

Set `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME` (default: `admin@flowx.ai`)

**Process:**

* System searches for this username in Keycloak
* Copies the user's `sub_id` (subject ID) to authorization-system database
* Grants organization admin privileges automatically

### Fallback method

Set `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID` with a specific Keycloak subject ID

**Process:**

* Creates user directly in authorization-system database
* Assigns organization admin roles
* Used when username method fails or is set to null

### Error handling

**If incorrect subject\_id is provided:**

* Login will fail
* No org-admin privileges granted
* Manual database correction required

<Info>
  If you've deployed with an incorrect subject\_id, use this SQL script to fix it:

  ```sql theme={"system"}
  -- Replace the incorrect subject_id with the correct one from Keycloak
  UPDATE public.cas_user
  SET subject_id = 'PASTE_CORRECT_SUBJECT_ID_FROM_KEYCLOAK_HERE'
  WHERE id = '00000000-0000-0000-0000-100000000001';
  ```

  The first organization administrator always has the ID `00000000-0000-0000-0000-100000000001` in the authorization-system database.
</Info>

## Keycloak redirect URIs

On first startup, the authorization-system runs a Liquibase migration that creates (or updates) the default Keycloak realm and configures the `flowx-platform-authenticate` client. You can control which redirect URIs are set on this client using:

```bash Environment Variables theme={"system"}
SPRING_LIQUIBASE_PARAMETERS_ALLOWEDREDIRECTURIS=https://designer.yourcompany.com/*,https://app.yourcompany.com/*
```

| Environment Variable                              | Description                                                                                               | Default Value |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------- |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWEDREDIRECTURIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client | ` ` (empty)   |

<Warning>
  For **new deployments**, if this variable is left empty, the Keycloak client will have **no redirect URIs configured** and OAuth2 login flows will fail. Set this to match your Designer and app URLs.

  For **existing deployments** upgrading to 5.5.0, the migration has already run and will not re-execute. Your current Keycloak redirect URIs remain unchanged.
</Warning>

**Examples:**

* `https://designer.yourcompany.com/*` — Designer access
* `https://app.yourcompany.com/*` — Container app access
* `http://localhost*` — Local development

<Tip>
  You can also configure redirect URIs manually in Keycloak after deployment. This variable only applies during the initial Liquibase migration. See the [IAM Configuration](./access-management/configuring-an-iam-solution) guide for manual Keycloak setup.
</Tip>

***

## Default realm admin credentials

During the initial Liquibase migration, the authorization-system creates the default FlowX Keycloak realm along with an admin user. You must set an initial password for this admin user:

| Environment Variable                                                      | Description                                                                                                               | Default Value    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`                     | Email/username for the default realm admin user                                                                           | `admin@flowx.ai` |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULTREALMADMININITIALPASSWORD`            | Initial password for the default realm admin user. The user will be required to change this password on first login.      | ` ` (empty)      |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULTREALMADMININITIALPASSWORDISTEMPORARY` | Whether the initial password is temporary. When `true`, the admin user is required to change the password on first login. | `true`           |

<Info>
  **Self-hosted deployments**: leave these variables empty. The bootstrap admin password is supplied through the first-time setup screen in Designer the first time the platform starts. See [Self-hosted initialization](./organization-manager-setup#self-hosted-initialization) for the registration flow.
</Info>

<Warning>
  For **new deployments**, this variable **must be set** to a non-empty value. If left empty, the Liquibase migration will fail with `Cannot create default realm` when attempting to create the default admin user, and the authorization-system will not start. The Keycloak realm itself may be created successfully, but the migration will still fail at the user creation step.

  For **existing deployments**, this parameter only applies during the initial migration. If the admin user already exists in the realm, it has no effect.
</Warning>

***

## Customer-specific variables

<Note>
  **Required Customization**: These variables must be updated for each deployment environment.
</Note>

* `SECURITY_OAUTH2_BASESERVERURL` — Your Keycloak server URL
* `SECURITY_MASTERREALM_ADMIN_PASSWORD` — Master realm admin password
* `SPRING_DATASOURCE_URL` — Your PostgreSQL connection details
* `SPRING_LIQUIBASE_PARAMETERS_ALLOWEDREDIRECTURIS` — Designer and app redirect URIs
* Service hostnames — Update to match your Kubernetes service names

## Secrets management

<Warning>
  **Security**: Always use Kubernetes Secrets for sensitive configuration values.
</Warning>

**Required Kubernetes Secrets:**

* `SPRING_DATASOURCE_PASSWORD`
* `FLOWX_SPICEDB_TOKEN`
* `SPRING_REDIS_PASSWORD`
* `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`
* `SECURITY_MASTERREALM_ADMIN_PASSWORD`

## Deployment prerequisites

<CardGroup>
  <Card title="Infrastructure" icon="server">
    * PostgreSQL with `authorization_system` database
    * SpiceDB with authentication configured
    * Redis for caching
  </Card>

  <Card title="Identity & Access" icon="users">
    * Keycloak with configured realm
    * OAuth2 clients created
    * Admin user exists in Keycloak
  </Card>
</CardGroup>

## Architecture notes

<Info>
  **Database Access Control**: Only authorization-system has direct write access to the CAS PostgreSQL database. Other services communicate via REST APIs only.
</Info>

<Info>
  **SpiceDB Integration**: Uses PostgreSQL as backend storage and communicates via gRPC through the CAS client library.
</Info>

## Ingress and CORS

The Authorization System is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives | Example client URL                  |
| ---------- | ------------- | ---------------- | ----------------------------------- |
| admin      | `/auth`       | `/`              | `https://admin.{host}/auth/api/...` |

The path is set through `services.authorization-system.ingress.admin.path` (or `services.authorization-system.gateway.admin.paths`) in the chart values. The `/auth` prefix is also used by Keycloak (configured separately via `global.flowx.idp.keycloak.contextPath`); the chart wires both behind the same prefix.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                                | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Authorization System. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).


# FlowX Designer setup
Source: https://docs.flowx.ai/5.9/setup-guides/designer-setup-guide

To set up FlowX Designer in your environment, follow this guide.

## Prerequisites management

### Ingress routing

The FlowX Designer is a single-page application (SPA) served from its own pod, with backend API calls proxied to the Process Engine, Application Manager, and the various plugins. Routing for the Designer and every backend service is rendered by the FlowX Helm chart — there is no separate hand-authored NGINX configuration in 5.9.x.

The Designer itself is exposed on the public host at `/` (path preserved), with a wildcard `*.public-host` rule that supports workspace-per-subdomain access. Each backend service the Designer calls has its own ingress rule rendered by the chart (see [Ingress configuration guide](./ingress-configuration) for the complete route reference).

For SPA-specific concerns — TLS, cookie affinity, custom domains — configure these through the chart values (`services.designer.ingress.public.annotations`, `services.designer.ingress.public.extraTls`) or share your requirements with FlowX so they are wired in during the upgrade.

Upgrading from 5.1.x? See [Ingress routing and CORS migration](/5.9/migrating-from-5.1-lts/ingress-routing) for the NGINX → chart-rendered routing transition.

***

## Steps to deploy Frontend app

The FlowX.AI Designer is an SPA application that is packaged in a docker image with `nginx`. The web application allows an authenticated user to administrate the FlowX platform. Environment variables are injected at container startup via `envsubst`.

### Application configuration

| Environment Variable             | Description                                                                   | Default Value |
| -------------------------------- | ----------------------------------------------------------------------------- | ------------- |
| `BASE_API_URL`                   | Backend API base URL (the host configured in the NGINX ingress)               | -             |
| `ADMIN_API_URL`                  | Admin API URL, used for admin-specific backend calls                          | -             |
| `PROCESS_API_PATH`               | API path prefix for the process engine (e.g. `/engine`)                       | -             |
| `STATIC_ASSETS_PATH`             | Public URL for static assets / media library CDN                              | -             |
| `BASE_HREF`                      | HTML base href override for non-root deployments                              | `/`           |
| `VERSION`                        | Application version string displayed in the UI                                | -             |
| `ROOT_DOMAIN`                    | Root domain for the application                                               | -             |
| `COLLABORATION_POLLING_INTERVAL` | Polling interval in milliseconds for collaboration features                   | -             |
| `LEGACY_HTTP_VERSION`            | Enables legacy HTTP polling mode with SSE reconnect on page visibility change | `false`       |

### Authentication (OpenID Connect)

| Environment Variable                   | Description                                                                        | Default Value          |
| -------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------- |
| `KEYCLOAK_ISSUER`                      | OpenID Connect provider issuer URL (e.g. `https://your-idp/auth/realms/realmName`) | -                      |
| `KEYCLOAK_REDIRECT_URI`                | OAuth redirect URI (URL of the SPA)                                                | -                      |
| `KEYCLOAK_CLIENT_ID`                   | OAuth client ID                                                                    | -                      |
| `KEYCLOAK_SCOPES`                      | OAuth scopes requested during authentication                                       | `openid profile email` |
| `DEFAULT_ORGANIZATION_NAME`            | Default organization name for login                                                | -                      |
| `REQUIRE_HTTPS`                        | Require HTTPS for OAuth communication                                              | `true`                 |
| `SHOW_DEBUG_INFORMATION`               | Show OAuth debug information in the browser console                                | `true`                 |
| `DISABLE_AT_HASH_CHECK`                | Disable `at_hash` claim validation                                                 | `false`                |
| `SKIP_ISSUER_CHECK`                    | Skip OAuth issuer URL validation                                                   | -                      |
| `STRICT_DISCOVERY_DOCUMENT_VALIDATION` | Enforce strict OIDC discovery document validation                                  | -                      |

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="NGINX configuration errors">
    **Symptoms:** 502 Bad Gateway or 404 errors when accessing the Designer.

    **Solutions:**

    1. Verify the ingress annotations are correct, especially `rewrite-target` paths
    2. Check that backend service names and ports match your Kubernetes service definitions
    3. Ensure CORS origins include all domains the Designer is accessed from
    4. Validate the `host` values in ingress rules match your DNS configuration
    5. Check NGINX controller logs for detailed routing errors: `kubectl logs -n ingress-nginx <controller-pod>`
  </Accordion>

  <Accordion title="SSO/authentication failures">
    **Symptoms:** Redirect loops, blank screens after login, or 401 errors.

    **Solutions:**

    1. Verify `KEYCLOAK_ISSUER` matches the realm URL exactly (including `/auth/realms/<realm>`)
    2. Ensure `KEYCLOAK_REDIRECT_URI` matches the SPA URL configured in the Keycloak client
    3. Check that the Keycloak client ID (`KEYCLOAK_CLIENT_ID`) exists and is enabled
    4. Confirm the Keycloak client has the correct redirect URIs and web origins configured
    5. Clear browser cookies and local storage, then try again
  </Accordion>

  <Accordion title="WebSocket connection issues">
    **Symptoms:** Real-time updates not working, SSE events not received, process testing hangs.

    **Solutions:**

    1. Verify the SSE ingress configuration routes `/api/events` to the events-gateway service
    2. Check that `nginx.ingress.kubernetes.io/cors-allow-headers` includes required headers
    3. Ensure the events-gateway service is running and healthy
    4. Confirm network policies allow traffic from the Designer ingress to the events-gateway pod
    5. Check for proxy timeout settings that may terminate long-lived connections
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Ingress Configuration" icon="globe" href="./ingress-configuration">
    Configure routing, CORS, and TLS for FlowX services
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Configuring access roles for processes
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes

Learn how to set up user role-based access control for process definitions using swimlanes, business filters, and permissions configuration.

Process access control in FlowX.AI is managed through a flexible role-based system that allows you to control who can access, view, and interact with different parts of your processes. This guide covers the complete setup and configuration of access roles for processes.

## Overview

FlowX.AI provides two main mechanisms for controlling process access:

* **Swimlanes**: Group process nodes by participants and control access at the node level
* **Business filters**: Restrict access based on dynamic business rules and user attributes

Both mechanisms work together to provide granular control over process security and user permissions.

## Prerequisites

Before configuring process access roles, ensure you have:

1. **Identity Provider Setup**: A configured identity provider (Keycloak, Entra ID, etc.) with user roles defined
2. **Service Account**: A service account with appropriate permissions in your identity provider
3. **Platform Configuration**: Proper platform configuration to connect to your identity provider

<Card title="Identity Provider Setup Guide" href="../designer-setup-guide#authorization--access-roles" icon="shield">
  Complete guide for setting up identity provider integration
</Card>

## Access control with swimlanes

### What are swimlanes?

Swimlanes provide a way of grouping process nodes by process participants. They allow you to ensure that only users with specific roles can access certain process nodes.

**Key characteristics:**

* By default, all process nodes belong to the same swimlane
* When a token moves between swimlanes, user access is evaluated
* Users without access to a swimlane will see the process in read-only mode
* Users receive notifications when access changes

### Configuring swimlanes

#### Step 1: Set up roles in identity provider

First, configure the desired user roles in your identity provider solution and assign users to the appropriate roles.

<Tip>
  Use the **Access Management** tab under **General Settings** in FlowX Designer to administrate all roles and view their current assignments.

  ![Access Management Roles](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/access_management_roles.png)
</Tip>

#### Step 2: Configure service account

<Info>
  A [service account](../access-management/configuring-an-iam-solution#process-engine-service-account) with appropriate permissions must be configured in your identity provider to allow FlowX.AI to access role information.
</Info>

#### Step 3: Configure swimlane permissions

Navigate to your process definition and access the **Permissions** tab in the process settings panel. Here you can configure access for each swimlane.

After defining roles in your identity provider solution, they will be available in the process definition settings panel for configuring swimlane access. When you create a new swimlane, it automatically comes with two default permissions assigned.

### Default swimlane permissions

Every process comes with a **Default** swimlane that includes two standard permissions:

<Frame>
  ![Default Swimlane Roles](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/swimlane_default_roles.png)
</Frame>

* **Execute**: You can start process instances and run actions on them
* **Self-assign**: You can assign process instances to themselves and begin working on them

<Info>
  These default permissions are available in FlowX.AI platform version **2.11.0 and later**.
</Info>

### Swimlane execution control

#### Allow multiple swimlane executors

For each swimlane, you can control execution permissions by switching between:

* **Swimlane owner + multiple executors** (default)
* **Only Swimlane Owner**

<Info>
  This setting can be configured individually for each swimlane in your process definition.
</Info>

<Frame>
  ![Allow Multiple Executors Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_multiple_executors.png)
</Frame>

When **multiple executors** is enabled, you gain additional flexibility to configure permissions at the UI Element level within User Tasks for the selected swimlane.

<Frame>
  ![Permission-Based UI Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pemission_%20based_ui.png)
</Frame>

This granular control allows you to:

* Assign different UI elements to different roles within the same swimlane
* Create more complex permission structures for sophisticated workflows
* Maintain security while enabling collaborative work on process instances

### Additional permissions

You can manually add additional permissions based on your specific requirements:

#### Core permissions

* **View**: View process instance data
* **Execute**: Start process instances and run actions
* **Self-assign**: Assign process instances to yourself

#### Task management permissions

These permissions are specifically for use with the [Task Management plugin](../../docs/platform-deep-dive/core-extensions/task-management/task-management-overview):

* **Assign**: Assign tasks to other users
* **Unassign**: Remove task assignments from other users
* **Hold**: Mark process instances as on hold
* **Unhold**: Remove hold status from process instances
* **Change Priority**: Modify task priority levels

<Frame>
  ![Process Permissions Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/process_permissions.png)
</Frame>

<Warning>
  **Version Compatibility**:

  * **2.11.0+**: Specific roles must be configured for each operation, otherwise restrictions will be applied
  * **\< 2.11.0**: If no role is configured, no restrictions are applied
</Warning>

## Access control with business filters

### What are business filters?

Business filters allow you to restrict process access based on dynamic business rules. For example, you might want only users from a specific bank branch to view process instances started from that branch.

### How business filters work

Business filters use attributes that are:

1. Configured in your identity management platform
2. Made available on the authorization token
3. Assigned to application users
4. Stored in process instance parameters

When a business filter is applied, only users with matching attributes can interact with the process instance.

### Configuring business filters

#### Step 1: Identity provider configuration

Configure business filter attributes in your identity provider as:

* A list of filters on the authorization token
* Attributes assigned to specific users

#### Step 2: Process definition setup

In your process definition, include nodes with actions that store the current business filter value to:

```
task.businessFilters
```

This value must be set in the process instance parameters.

#### Step 3: Runtime behavior

Once configured, only users with the correct business filter attribute can interact with process instances that have the filter applied.

<Card title="Business Filters Guide" href="../../docs/platform-deep-dive/user-roles-management/business-filters" icon="filter">
  Detailed guide on implementing business filters
</Card>

## Configuration examples

### Standard user configuration

For regular users who need basic process interaction:

![Regular User Roles Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/regular_user_roles.png)

```yaml theme={"system"}
Permissions:
  - execute: USER_ROLE
  - self-assign: USER_ROLE  
  - view: USER_ROLE
```

### Administrator configuration

For administrators who need full process management capabilities:

![Admin User Roles Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/admin_user_roles.png)

```yaml theme={"system"}
Permissions:
  - execute: ADMIN_ROLE
  - self-assign: ADMIN_ROLE
  - view: ADMIN_ROLE
  - assign: ADMIN_ROLE
  - unassign: ADMIN_ROLE
  - hold: ADMIN_ROLE
  - unhold: ADMIN_ROLE
  - change-priority: ADMIN_ROLE
```

### Team lead configuration

For team leads who can manage their team's tasks:

```yaml theme={"system"}
Permissions:
  - execute: TEAM_LEAD_ROLE
  - self-assign: TEAM_LEAD_ROLE
  - view: TEAM_LEAD_ROLE
  - assign: TEAM_LEAD_ROLE
  - unassign: TEAM_LEAD_ROLE
```

## Platform configuration

### Engine configuration

Configure the FlowX Engine with the necessary environment variables for your identity provider:

#### Required variables

```bash theme={"system"}
SECURITY_TYPE=jwt-public-key
SECURITY_OAUTH2_BASESERVERURL=https://your-keycloak-server.com
SECURITY_OAUTH2_SAREALM=00000002-0002-4002-8002-000000000002
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID=flowx-process-engine-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET={your-sa-client-secret}
```

#### Optional variables

```bash theme={"system"}
# Data anonymization for sensitive information
FLOWX_DATA_ANONYMIZATION=true
```

### REST API access control

To restrict API calls by user role, configure path authorizations:

```yaml theme={"system"}
security:
  pathAuthorizations:
    - path: "/api/**"
      rolesAllowed: "ANY_AUTHENTICATED_USER"
    - path: "/api/admin/**"  
      rolesAllowed: "ADMIN_ROLE"
```

## Process instance management

### Viewing process instances

You can view active process instances and their data from FlowX Designer if you have the appropriate role (default: `FLOWX_ROLE`).

**Data Privacy**: Use the `FLOWX_DATA_ANONYMIZATION` environment variable to configure whether sensitive user data should be hidden in process views.

### Starting processes

The `FLOWX_ROLE` (or your configured default role) is required for users to start new process instances.

## Troubleshooting

### Common issues

**Users can't see processes**: Verify that the correct roles are assigned in your identity provider and that the service account is properly configured.

**Permission denied errors**: Check that the required permissions are configured for the specific operations and that users have the appropriate roles.

**Business filters not working**: Ensure that business filter attributes are properly configured in the identity provider and available on the authorization token.

### Version-specific considerations

<Warning>
  **Platform Version \< 2.11.0**: If no role is configured on an operation, no restrictions will be applied. This behavior changed in version 2.11.0 where explicit role configuration became mandatory.
</Warning>

## Best practices

1. **Principle of Least Privilege**: Only grant the minimum permissions necessary for users to perform their tasks

2. **Role Hierarchy**: Design roles hierarchically (e.g., Admin > Team Lead > User) to simplify management

3. **Regular Audits**: Periodically review role assignments and permissions to ensure they remain appropriate

4. **Documentation**: Maintain clear documentation of what each role can do and who should have each role

5. **Testing**: Always test permission changes in a non-production environment first

6. **Business Filters**: Use business filters for dynamic, data-driven access control rather than static role-based restrictions

## Related topics

<CardGroup>
  <Card title="Swimlanes" href="../../docs/platform-deep-dive/user-roles-management/swimlanes" icon="swimming-pool">
    Detailed swimlanes configuration guide
  </Card>

  <Card title="Business filters" href="../../docs/platform-deep-dive/user-roles-management/business-filters" icon="filter">
    Advanced business rules for access control
  </Card>
</CardGroup>


# Configuring Elasticsearch indexing
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing

This guide shows you how to enable process instance indexing using either Kafka or HTTP transport strategies.

<Info>
  **Scope.** This guide covers process-instance indexing only — the `process_instance-*` indices written by `process-engine`. Audit logs (`audit-logs` index, written directly by `audit-core` over HTTPS) and search workloads (`data-search`, read-only) do **not** flow through this pipeline.
</Info>

## Before you start

* **Read the prerequisites**: Review the [Intro to Elasticsearch](../../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch) section first
* **Choose your strategy**: Decide between Kafka (recommended for production) or HTTP indexing based on your infrastructure
* **Check permissions**: Ensure you have access to modify process-engine configurations

## Quick decision: Kafka vs HTTP

| Strategy                | Best for                                     | Pros                                                                                               | Cons                                                              |
| ----------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Kafka** (recommended) | Production environments with high throughput | Fire-and-forget communication, time-based partitioning, better performance, decoupled architecture | Requires Kafka Connect setup                                      |
| **HTTP**                | Development or simple setups                 | Direct connection, easier setup                                                                    | Blocking operations, no time-based partitioning, tighter coupling |

<Tip>
  **Why Kafka is recommended**: The Kafka strategy allows for fire-and-forget communication, eliminating the need for the process engine to wait for indexing requests to complete. This significantly improves performance in high-throughput scenarios.
</Tip>

<Info>
  **Critical difference**: Only the Kafka strategy provides out-of-the-box support for time-based partitioning through the `transforms.routeTS.timestamp.format` configuration (see later in this guide). The HTTP strategy does not support time-based partitioning as a built-in feature.
</Info>

***

## Configuration overview

All indexing is controlled by these core settings:

### Global indexing control

```bash theme={"system"}
FLOWX_INDEXING_ENABLED=false  # Set only when you want to disable indexing
```

<Info>
  `FLOWX_INDEXING_ENABLED` defaults to true. Only set this variable if you want to disable indexing by setting it to false.
</Info>

### Strategy selection

```bash theme={"system"}
FLOWX_INDEXING_TYPE=kafka  # Options: kafka, http, no-indexing
```

### Performance considerations (FlowX defaults)

**Default configuration:**

* **Monthly indices**: `yyyyMM` format for time-based partitioning (Kafka only)
* **2 shards + 0 replicas** (code default): bump replicas based on your high-availability requirements
* **Primary shards per year**: 24 (2 primary × 12 monthly indices) — well under Elasticsearch's 1000 shard default limit; each replica adds another 24

**Scaling guidelines:**

* **If indexing becomes slow**: Check physical resources and shard size
* **If monthly indices become too large**: Switch to weekly indices (`yyyyww`)
* **For high parallel indexing load**: Add more primary shards
* **High availability**: Set `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` to at least `1` in production for resilience to a single node loss

<Warning>
  **Important**: Each replica is applied per shard, so monitor resource usage when increasing replicas.
</Warning>

### HTTP-only setting

```bash theme={"system"}
FLOWX_INDEXING_OPTIMISTICLOCKINGRETRIES=3  # Only used with HTTP strategy
```

***

## Setup: Kafka indexing (recommended)

### Step 1: Configure the process engine

Add these environment variables to your process-engine configuration:

```bash theme={"system"}
# Elasticsearch connection settings
SPRING_ELASTICSEARCH_REST_PROTOCOL=https
SPRING_ELASTICSEARCH_REST_URIS=elasticsearch:9200
SPRING_ELASTICSEARCH_REST_DISABLESSL=false
SPRING_ELASTICSEARCH_REST_USERNAME=
SPRING_ELASTICSEARCH_REST_PASSWORD=

# Use Kafka strategy
FLOWX_INDEXING_TYPE=kafka

# Index settings (optional - these are the defaults)
FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME=process_instance
FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS=2
FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=0
```

<Warning>
  **`process-engine` still needs HTTPS connectivity to Elasticsearch in Kafka mode.** Even with `FLOWX_INDEXING_TYPE=kafka`, `process-engine` creates the `process_instance_template` index template directly against Elasticsearch at startup. If `process-engine` cannot reach Elasticsearch, the template silently fails to apply and indices fall back to default mappings — search and aggregations break in non-obvious ways.
</Warning>

### Step 2: Deploy Kafka Connect

#### Compatibility matrix

| Component                           | Supported in 5.9.0                                         |
| ----------------------------------- | ---------------------------------------------------------- |
| Kafka cluster                       | 3.9 – 4.2 (set `KafkaConnect.spec.version` to match)       |
| Elasticsearch Sink Connector plugin | 15+                                                        |
| Elasticsearch (target cluster)      | 8.x                                                        |
| Kafka Connect runtime               | matches Kafka cluster version, run by the Strimzi operator |

<Note>
  Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version deployed. This guide uses the Confluent `kafka-connect-elasticsearch` plugin as the reference path.
</Note>

**Prerequisites:**

* Kafka cluster (installed with Strimzi operator)
* Elasticsearch cluster (installed with eck-operator)
* Convert ES certificates to JKS format (see commands below)

**Certificate conversion commands:**

```bash theme={"system"}
# 1. Extract the CA certificate
kubectl get secret elasticsearch-es-http-certs-public -n flowx \
  -o jsonpath='{.data.ca\.crt}' | base64 --decode > es-ca.crt

# 2. Create JKS keystore
keytool -importcert -alias elasticsearch -file es-ca.crt \
  -keystore keystore.jks -storepass flowx123456 -noprompt

# 3. Create Kubernetes secret
kubectl -n flowx create secret generic kafka-connect-elastic-jks --from-file=keystore.jks
```

**Deploy KafkaConnect:**

<Warning>
  **FlowX does not publish a Kafka Connect image.** You build and host the container image yourself. Strimzi's `spec.build` block below downloads the connector plugin, bakes it into a new image, and pushes it to your registry. Use an immutable tag that ties the image to the plugin version so upgrades are auditable.
</Warning>

```yaml theme={"system"}
apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaConnect
metadata:
  name: flowx-elasticsearch-kafka-connect
  annotations:
    strimzi.io/use-connector-resources: "true"
spec:
  version: 3.9.0  # FlowX 5.9 supports Kafka 3.9 – 4.2; set this to your deployed cluster version
  replicas: 1
  bootstrapServers: flowx-kafka-bootstrap:9092

  # OAuth configuration (if using Keycloak)
  authentication:
    type: oauth
    clientId: flowx-service-client
    clientSecret:
      secretName: keycloak-kafka-cluster-client
      key: KEYCLOAK_KAFKA_CLUSTER_CLIENT_SECRET
    tokenEndpointUri: https://YOUR_KEYCLOAK_URL/auth/realms/YOUR_REALM/protocol/openid-connect/token
    tlsTrustedCertificates:
      - secretName: self-signed-certificate
        certificate: tls.crt
    disableTlsHostnameVerification: true

  config:
    group.id: flowx-kafka-connect-es-plugin
    offset.storage.topic: ai.flowx.kafka-connect-cluster-offsets
    config.storage.topic: ai.flowx.kafka-connect-cluster-configs
    status.storage.topic: ai.flowx.kafka-connect-cluster-status
    config.storage.replication.factor: -1
    offset.storage.replication.factor: -1
    status.storage.replication.factor: -1
    # Auto-creates Kafka Connect's internal bookkeeping topics (offsets / configs / status).
    # The SOURCE topic (ai.flowx.<env>.core.index.process.v1) is NOT covered here — you must
    # declare it via your Strimzi KafkaTopic resources before starting the connector.
    topic.creation.enable: true
    config.providers: env
    config.providers.env.class: org.apache.kafka.common.config.provider.EnvVarConfigProvider

  build:
    output:
      type: docker
      # YOU build and host this image. FlowX does not publish a Kafka Connect image.
      # Strimzi pulls the upstream Connect base, downloads the plugin below, bakes a new
      # container, and pushes it here. Tag it with the plugin version for traceability.
      image: <YOUR_REGISTRY>/<your-connect-image-name>:<your-tag>
      pushSecret: registry-credentials  # K8s secret of type kubernetes.io/dockerconfigjson
    plugins:
      - name: kafka-connect-elasticsearch
        artifacts:
          - type: zip
            url: https://hub-downloads.confluent.io/api/plugins/confluentinc/kafka-connect-elasticsearch/versions/15.1.2/confluentinc-kafka-connect-elasticsearch-15.1.2.zip
            # sha512sum: <recommended for supply-chain integrity — fill in the published checksum>

  template:
    pod:
      volumes:
        - name: elasticsearch-keystore
          secret:
            secretName: kafka-connect-elastic-jks
    connectContainer:
      env:
        - name: ELASTIC_PASSWORD
          valueFrom:
            secretKeyRef:
              name: elasticsearch-es-elastic-user
              key: elastic
      volumeMounts:
        - name: elasticsearch-keystore
          mountPath: /mnt/elasticsearch-keystore
          readOnly: true
```

### Step 3: Configure the Elasticsearch Sink Connector

<Warning>
  **Indices are partitioned by process start month, not update month.** The `TimestampRouter` uses the Kafka record timestamp, which `process-engine` populates with the process instance's `dateStarted`. Late updates to old process instances land in the *original* start-month index, not the index for the current month. Plan archiving alignment accordingly, and use the body field `indexLastUpdatedTime` (not the index name) for "activity in last X days" queries.
</Warning>

<Warning>
  **The source topic must be pre-declared.** `topic.creation.enable: true` on the `KafkaConnect` cluster only creates Kafka Connect's internal offsets/configs/status topics — it does **not** create the source topic the connector consumes. Add `ai.flowx.<env>.core.index.process.v1` to your Strimzi `KafkaTopic` resources before the connector starts.
</Warning>

**Key settings explained:**

* `transforms.routeTS.timestamp.format`: Controls index partitioning (monthly=`yyyyMM`, daily=`yyyyMMdd`)
* `transforms.routeTS.topic.format`: Must start with your configured index name
* `batch.size`: Adjust based on throughput needs (1000 is good default)

<Warning>
  **Process instance data archiving integration**: If you're using FlowX's process instance data archiving feature, ensure your Elasticsearch partitioning configuration aligns with your database partitioning strategy. This is essential because:

  * When archiving process instances, data must be deleted from both the database and Elasticsearch
  * The partitioning intervals should be similar between database and Elasticsearch for consistent data lifecycle management
  * Elasticsearch indexing strategy must be enabled when partitioning is configured
</Warning>

```yaml theme={"system"}
apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaConnector
metadata:
  name: flowx-elasticsearch-sink-connector
  labels:
    strimzi.io/cluster: flowx-elasticsearch-kafka-connect
spec:
  class: io.confluent.connect.elasticsearch.ElasticsearchSinkConnector
  config:
    # Connection settings - UPDATE THESE
    connection.url: https://elasticsearch-es-http.flowx.svc:9200
    connection.username: elastic
    connection.password: ${env:ELASTIC_PASSWORD}
    
    # SSL settings
    elastic.security.protocol: SSL
    elastic.https.ssl.truststore.type: JKS
    elastic.https.ssl.truststore.location: /mnt/elasticsearch-keystore/keystore.jks
    elastic.https.ssl.truststore.password: "flowx123456"
    
    # Source topic - must match your Kafka topic naming
    topics: ai.flowx.core.index.process.v1
    
    # Time-based routing - IMPORTANT: Choose your partitioning strategy
    transforms: routeTS
    transforms.routeTS.type: org.apache.kafka.connect.transforms.TimestampRouter
    transforms.routeTS.timestamp.format: yyyyMM  # Monthly indices (change as needed)
    transforms.routeTS.topic.format: process_instance-${timestamp}  # Must start with your index name
    
    # Performance settings
    batch.size: 1000
    read.timeout.ms: 30000
    flush.synchronously: "true"
    
    # Data handling
    behavior.on.malformed.documents: IGNORE
    behavior.on.null.values: IGNORE
    drop.invalid.message: "true"
    schema.ignore: "true"
    write.method: UPSERT
    type.name: _doc
    
    # Converters
    key.converter: org.apache.kafka.connect.storage.StringConverter
    key.converter.schemas.enable: "false"
    value.converter: org.apache.kafka.connect.json.JsonConverter
    value.converter.schemas.enable: "false"
```

### Step 4: Verify the setup

**Check Kafka Connect status:**

```bash theme={"system"}
kubectl get kafkaconnect flowx-elasticsearch-kafka-connect -o yaml
```

**Check connector status:**

```bash theme={"system"}
kubectl get kafkaconnector flowx-elasticsearch-sink-connector -o yaml
```

**Verify indices are being created:**

```bash theme={"system"}
# Port-forward to Elasticsearch
kubectl port-forward svc/elasticsearch-es-http 9200:9200

# Check indices (should see process_instance-YYYYMM pattern)
curl -k -u elastic:$ELASTIC_PASSWORD https://localhost:9200/_cat/indices?v
```

***

## Setup: HTTP indexing (simple)

### Configure the process engine

For HTTP indexing, update your process-engine configuration:

```bash theme={"system"}
# Elasticsearch connection settings
SPRING_ELASTICSEARCH_REST_PROTOCOL=https
SPRING_ELASTICSEARCH_REST_URIS=elasticsearch:9200
SPRING_ELASTICSEARCH_REST_DISABLESSL=false
SPRING_ELASTICSEARCH_REST_USERNAME=
SPRING_ELASTICSEARCH_REST_PASSWORD=

# Use HTTP strategy
FLOWX_INDEXING_TYPE=http

# Index settings (optional - these are the defaults)
FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME=process_instance
FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS=2
FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=0

# HTTP-specific setting
FLOWX_INDEXING_OPTIMISTICLOCKINGRETRIES=3
```

***

## Kafka topics

The process engine publishes indexing records to a topic whose name is composed from the standard FlowX Kafka naming triple:

```
<package><environment>core.index.process<version>
```

Each segment is set independently via environment variables on the `process-engine` deployment:

| Environment Variable             | Typical value          | Notes                                     |
| -------------------------------- | ---------------------- | ----------------------------------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | `ai.flowx.`            | Vendor prefix. Same for all FlowX topics. |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | `dev.` or \`\` (empty) | Environment segment. Empty in production. |
| `KAFKA_TOPIC_NAMING_VERSION`     | `.v1`                  | Schema version suffix.                    |

**Worked examples:**

| Environment                       | Composed source topic                |
| --------------------------------- | ------------------------------------ |
| Dev (`ENVIRONMENT=dev.`)          | `ai.flowx.dev.core.index.process.v1` |
| Production (`ENVIRONMENT=` empty) | `ai.flowx.core.index.process.v1`     |

**Important:** The `topics:` value in your `KafkaConnector` configuration must match the composed topic for your environment. You must also declare that topic explicitly via your Strimzi `KafkaTopic` resources — see the warning under Step 3.

***

## Index management

### Automatic template creation

The process engine automatically creates Elasticsearch index templates during startup:

* **HTTP strategy**: Creates the index directly with configured shards/replicas
* **Kafka strategy**: Creates an index template that applies to dynamically created indices

### Time-based partitioning (Kafka only)

Choose your partitioning strategy based on data volume and retention needs:

| Database Partitioning | Elasticsearch Format | Index Pattern               | Best For         |
| --------------------- | -------------------- | --------------------------- | ---------------- |
| Monthly               | `yyyyMM`             | `process_instance-202406`   | Medium volume    |
| Weekly                | `yyyyww`             | `process_instance-202426`   | High volume      |
| Daily                 | `yyyyMMdd`           | `process_instance-20240615` | Very high volume |

### Efficient data deletion

**Best practice:** Delete entire indices rather than individual documents for better performance.

With time-based partitioning, you can:

```bash theme={"system"}
# Delete old monthly index
curl -X DELETE "https://localhost:9200/process_instance-202401"

# Delete multiple old indices
curl -X DELETE "https://localhost:9200/process_instance-2024*"
```

***

## Troubleshooting

### Common issues

**Indexing not working:**

1. Check if indexing is disabled (only if you explicitly set `FLOWX_INDEXING_ENABLED=false`)
2. Verify Elasticsearch connectivity
3. Check process-engine logs for errors

**Kafka Connect issues:**

```bash theme={"system"}
# Check connect cluster status
kubectl describe kafkaconnect flowx-elasticsearch-kafka-connect

# Check connector logs
kubectl logs -l strimzi.io/kind=KafkaConnect -f
```

**Certificate issues:**

```bash theme={"system"}
# Verify JKS keystore
keytool -list -keystore keystore.jks -storepass flowx123456

# Check secret exists
kubectl get secret kafka-connect-elastic-jks -o yaml
```

**Performance issues:**

* Increase `batch.size` in connector config
* Adjust number of shards based on cluster size
* Monitor Elasticsearch cluster health

### Verification queries

**Check index pattern:**

```bash theme={"system"}
# List all process instance indices
curl -k -u elastic:$PASSWORD "https://localhost:9200/_cat/indices/process_instance*?v"

# Check template exists
curl -k -u elastic:$PASSWORD "https://localhost:9200/_template/process_instance*"
```

**Query across time-based indices:**

```bash theme={"system"}
# Search across all process instance indices
curl -k -u elastic:$PASSWORD -X GET "https://localhost:9200/process_instance-*/_search" \
  -H "Content-Type: application/json" \
  -d '{"query": {"match_all": {}}}'
```


# Indexing config guidelines
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/process-instance-indexing-config-guidelines

Guidelines for sizing and configuring Elasticsearch for process instance indexing based on app load and indexed keys per process.

## Indexing strategy

* Advantages of Multiple Small Indices:
  * Fast indexing process.
  * Flexibility in cleaning up old data.
* Potential Drawbacks:
  * Hitting the maximum number of shards per node, resulting in exceptions when creating new indices.
  * Increased search response time and memory footprint.
* Deletion
  * When deleting data in Elasticsearch, it's recommended to delete entire indices instead of individual documents. Creating multiple smaller indices provides the flexibility to delete entire indices of old data that are no longer needed.

Alternatively, you can create fewer indices that span longer periods of time, such as one index per year. This approach offers small search response times but may result in longer indexing times and difficulty in cleaning up and recovering data in case of failure.

<Card title="What is indexing?" href="../../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch#indexing" icon="question" />

## Shard and replica configuration

The solution includes an index template that gets created with the settings from the process-engine app (name, shards, replicas) when running the app for the first time. This template controls the settings and mapping of all newly created indices.

<Card title="What is sharding?" href="../../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch#sharding" icon="question" />

<Card title="Index template" href="./elasticsearch-indexing#elasticsearch-update-index-template" icon="file" />

Once an index is created, you cannot update its number of shards and replicas. However, you can update the settings from the index template at runtime in Elasticsearch, and new indices will be created with the updated settings. Note that the mapping should not be altered as it is required by the application.

## Recommendations for resource management

To manage functional indexing operations and resources efficiently, consider the following recommendations:

* [Sizing indexes upon creation](#sizing-indexes-upon-creation)
* [Balancing](#balancing)
* [Delete unneeded indices](#delete-unneeded-indices)
* [Reindex large indices](#reindex-large-indices)
* [Force merge indices](#force-merge-indices)
* [Shrink indices](#shrink-indices)
* [Combine indices](#combine-indices)

#### Sizing indexes upon creation

Recommendations:

* Start with monthly indexes that have 2 shards and 1 replica. This setup is typically sufficient for handling up to 200k process instances per day; ensures a parallel indexing in two main shards and has also 1 replica per each main shard (4 shards in total). This would create 48 shards per year in the Elasticsearch nodes; A lot less than the default 1000 shards, so you will have enough space for other indexes as well.
  * If you observe that the indexing gets really, really slow, then you should look at the physical resources / shard size and start adapting the config.
  * If you observe that indexing one monthly index gets massive and affects the performance, then think about switching to weekly indices.
  * If you have huge spikes of parallel indexing load (even though that depends on the Kafka connect cluster configuration), then think about adding more main shards.
* Consider having at least one replica for high availability. However, keep in mind that the number of replicas is applied to each shard, so creating many replicas may lead to increased resource usage.
* Monitor the number of shards created and estimate when you might reach the maximum shards per node, taking into account the number of nodes in your cluster.

#### Balancing

When configuring index settings, consider the number of nodes in your cluster. The total number of shards (calculated by the formula: primary\_shards\_number \* (replicas\_number +1)) for an index should be directly proportional to the number of nodes. This helps Elasticsearch distribute the load evenly across nodes and avoid overloading a single node. Avoid adding shards and replicas unnecessarily.

#### Delete unneeded indices

Deleting unnecessary indices reduces memory footprint, the number of used shards, and search time.

#### Reindex large indices

If you have large indices, consider reindexing them. Process instance indexing involves multiple updates on an initially indexed process instance, resulting in multiple versions of the same document in the index. Reindexing creates a new index with only the latest version, reducing storage size, memory footprint, and search response time.

#### Force merge indices

If there are indices with no write operations performed anymore, perform force merge to reduce the number of segments in the index. This operation reduces memory footprint and response time. Only perform force merge during off-peak hours when the index is no longer used for writing.

#### Shrink indices

If you have indices with many shards, consider shrinking them using the shrink operation. This reindexes the data into an index with fewer shards. Perform this operation during off-peak hours.

#### Combine indices

If there are indices with no write operations performed anymore (e.g., process\_instance indices older than 6 months), combine these indices into a larger one and delete the smaller ones. Use the reindexing operation during off-peak hours. Ensure that write operations are no longer needed from the FLOWX platform for these indices.


# FlowX Engine setup
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/engine-setup

This guide provides instructions on how to set up and configure the FlowX.AI Engine.

## Infrastructure prerequisites

Before installing the FlowX.AI Engine, verify that the following infrastructure components are installed and configured:

* **Kafka**
* **Elasticsearch**
* **PostgreSQL** or **Oracle**
* **MongoDB**

***

## Dependencies

The FlowX Engine requires the following components:

* **Database**: Primary storage for the engine (PostgreSQL or Oracle)
* **Redis Server**: Used for caching. See [Redis Configuration](#redis-configuration)
* **Kafka**: Handles messaging and event-driven architecture. See [Configuring Kafka](#configuring-kafka)

For a microservices architecture, services typically manage their data via dedicated databases.

### Required external services

* **Redis Cluster**: Caches process definitions, compiled scripts, and Kafka responses
* **Kafka Cluster**: Enables communication with external plugins and integrations

***

## Configuration setup

FlowX.AI Engine uses environment variables for configuration. This section covers key configuration areas:

* [Database configuration](#database-configuration)
* [Authorization & access roles](#authorization--access-roles)
* [Kafka configuration](#configuring-kafka)
* [File upload size](#configuring-file-upload-size)
* [Elasticsearch connection](#configuring-elasticsearch-connection)

### Database configuration

The FlowX Engine supports both PostgreSQL and Oracle as its primary relational database.

#### PostgreSQL

| Environment variable                | Description                 |
| ----------------------------------- | --------------------------- |
| `SPRING_DATASOURCE_URL`             | Database URL for PostgreSQL |
| `SPRING_DATASOURCE_USERNAME`        | Username for PostgreSQL     |
| `SPRING_DATASOURCE_PASSWORD`        | Password for PostgreSQL     |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | Driver class for PostgreSQL |

#### Oracle

| Environment variable                | Description             |
| ----------------------------------- | ----------------------- |
| `SPRING_DATASOURCE_URL`             | Database URL for Oracle |
| `SPRING_DATASOURCE_USERNAME`        | Username for Oracle     |
| `SPRING_DATASOURCE_PASSWORD`        | Password for Oracle     |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | Driver class for Oracle |

**Default:** `oracle.jdbc.OracleDriver`

#### MongoDB configuration

Configure connection to the Runtime MongoDB instance:

| Environment variable              | Description                                                                                                                              | Default value                                                                                                         |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for connecting to Runtime MongoDB. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/app-runtime?retryWrites=false` |

### Configuration parameters

There are two types of Config Params that can be read from the environment: **variables** and **secrets**. There is one provider for variables and secrets extracted from the environment variables, and two providers for the ones extracted from Kubernetes. By default, the variables and secrets are extracted from environment variables (`env` provider).

#### Configuration parameters from environment variables (default)

The `env` provider used for variables and secrets extracts them from environment variables. For security reasons, the `env` provider uses an allow list regex which defaults to `FLOWX_CONFIGPARAM_.*`. This means only environment variables that match this naming pattern can be read at runtime into configuration params (either as variables or secrets). Feel free to edit it to match the environment variables that you use in your deployment.

| Environment variable                        | Description                                                     | Default value          |
| ------------------------------------------- | --------------------------------------------------------------- | ---------------------- |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER`          | Provider type for variables                                     | `env`                  |
| `FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX`    | Regular expression to match allowed env variables for variables | `FLOWX_CONFIGPARAM_.*` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER`       | Provider type for secrets                                       | `env`                  |
| `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX` | Regular expression to match allowed env variables for secrets   | `FLOWX_CONFIGPARAM_.*` |

#### Configuration parameters from Kubernetes Secrets and ConfigMaps

Use the following configuration to read Config Params from Kubernetes Secrets and ConfigMaps:

| Environment variable                  | Description                 | Values           |
| ------------------------------------- | --------------------------- | ---------------- |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER`    | Provider type for variables | `k8s-configmaps` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | Provider type for secrets   | `k8s-secrets`    |

These providers can be configured as follows:

| Environment variable                                           | Description                                | Values               |
| -------------------------------------------------------------- | ------------------------------------------ | -------------------- |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_0_` | Name of the ConfigMap to use for variables | `flowx-configparams` |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_0_`       | Name of the Secret to use for secrets      | `flowx-configparams` |

<Info>
  You can configure multiple secrets and ConfigMaps by incrementing the index number (e.g., `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_1`, `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_1`). Values are overridden based on the order in which the maps are defined.

  The default provider is `env`, but there is a built-in allowlist with the regex pattern `FLOWX_CONFIGPARAM_.*`. This means only configuration parameters that match this naming pattern can be read at runtime, whether they are environment variables or secret variables.
</Info>

#### Config params cache

Configure caching behavior for configuration parameters to optimize performance:

| Environment variable                  | Description                                             | Default value |
| ------------------------------------- | ------------------------------------------------------- | ------------- |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120`         |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache    | `500`         |

<Info>
  These settings control how long configuration parameters are cached in memory before being refreshed from the source (environment variables, ConfigMaps, or Secrets). Adjust these values based on how frequently your configuration changes and your memory constraints.
</Info>

### Authorization & access roles

This section covers OAuth2 configuration settings for securing the Spring application.

#### Security configuration

| Environment variable                         | Description                                            | Default value                       |
| -------------------------------------------- | ------------------------------------------------------ | ----------------------------------- |
| `SECURITY_TYPE`                              | Token validation mechanism (JWT public key validation) | `jwt-public-key`                    |
| `SECURITY_BASIC_ENABLED`                     | Enable basic authentication                            | `false`                             |
| `SECURITY_PUBLICPATHS_0`                     | Public path not requiring authentication               | `/api/platform/components-versions` |
| `SECURITY_PUBLICPATHS_1`                     | Public path not requiring authentication               | `/manage/actuator/health`           |
| `SECURITY_PATHAUTHORIZATIONS_0_PATH`         | Security path pattern                                  | `"/api/**"`                         |
| `SECURITY_PATHAUTHORIZATIONS_0_ROLESALLOWED` | Roles allowed for path access                          | `"ANY_AUTHENTICATED_USER"`          |

#### Service-to-service authentication

The engine validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment variable                                                        | Description                                                                                                                                           | Default value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-process-engine-sa`                                                                          |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

<Info>
  When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.
</Info>

For more information about the necessary service account, see [Process Engine Service Account](../access-management/configuring-an-iam-solution#process-engine-service-account).

### Configuring Kafka

Kafka handles all communication between the FlowX.AI Engine, external plugins, and integrations. It also notifies running process instances when certain events occur.

#### Kafka connection settings

| Environment variable      | Description                                                              | Default value    |
| ------------------------- | ------------------------------------------------------------------------ | ---------------- |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka bootstrap servers (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)     | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT`      |

#### Message routing configuration

| Environment variable       | Description                                                           | Default value       |
| -------------------------- | --------------------------------------------------------------------- | ------------------- |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

<Info>
  When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.
</Info>

#### Kafka consumer retry settings

| Environment variable               | Description                                                       | Default value |
| ---------------------------------- | ----------------------------------------------------------------- | ------------- |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Interval between retries after `AuthorizationException` (seconds) | `10`          |

#### Consumer groups & consumer threads configuration

Both a producer and a consumer must be configured:

<CardGroup>
  <Card title="Configuring a Kafka Producer" href="../../docs/platform-deep-dive/integrations/creating-a-kafka-producer" />

  <Card title="Configuring a Kafka Consumer" href="../../docs/platform-deep-dive/integrations/creating-a-kafka-consumer" />
</CardGroup>

<Frame>
  ![FlowX Engine Kafka communication pattern](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/engine_kafka_pattern.svg)
</Frame>

##### About consumer groups and threads

A consumer group is a set of consumers that jointly consume messages from one or more Kafka topics. Each consumer group has a unique identifier (group ID) that Kafka uses to manage message distribution.

Thread numbers refer to the number of threads a consumer application uses to process messages. Increasing thread count can improve parallelism and efficiency, especially with high message volumes.

##### Consumer group configuration

| Environment variable                             | Description                                                         | Default value              |
| ------------------------------------------------ | ------------------------------------------------------------------- | -------------------------- |
| `KAFKA_CONSUMER_GROUPID_NOTIFYADVANCE`           | Group ID for notifying advance actions                              | `advance`                  |
| `KAFKA_CONSUMER_GROUPID_NOTIFYPARENT`            | Group ID for notifying when a subprocess is blocked                 | `notify-parent`            |
| `KAFKA_CONSUMER_GROUPID_ADAPTERS`                | Group ID for messages related to adapters                           | `adapters`                 |
| `KAFKA_CONSUMER_GROUPID_SCHEDULERRUNACTION`      | Group ID for running scheduled actions                              | `scheduler-run-action`     |
| `KAFKA_CONSUMER_GROUPID_SCHEDULERADVANCING`      | Group ID for messages indicating continuing advancement             | `scheduler-advancing`      |
| `KAFKA_CONSUMER_GROUPID_MESSAGEEVENTS`           | Group ID for message events                                         | `message-events`           |
| `KAFKA_CONSUMER_GROUPID_PROCESS_START`           | Group ID for starting processes                                     | `process-start`            |
| `KAFKA_CONSUMER_GROUPID_PROCESS_STARTFOREVENT`   | Group ID for starting processes for an event                        | `process-start-for-event`  |
| `KAFKA_CONSUMER_GROUPID_PROCESS_EXPIRE`          | Group ID for expiring processes                                     | `process-expire`           |
| `KAFKA_CONSUMER_GROUPID_PROCESS_OPERATIONS`      | Group ID for processing operations from Task Management plugin      | `process-operations`       |
| `KAFKA_CONSUMER_GROUPID_PROCESS_BATCHPROCESSING` | Group ID for processing bulk operations from Task Management plugin | `process-batch-processing` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE`    | Group ID for processing UI flow session variable updates            | `ui-flow-update`           |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`    | Group ID for processing UI flow session expiry triggers             | `ui-flow-expire`           |
| `KAFKA_CONSUMER_GROUPID_CONFIGPARAMS`            | Group ID for runtime config-param change events                     | `config-params`            |

##### Consumer thread configuration

| Environment variable                             | Description                                                           | Default value |
| ------------------------------------------------ | --------------------------------------------------------------------- | ------------- |
| `KAFKA_CONSUMER_THREADS_NOTIFYADVANCE`           | Number of threads for notifying advance actions                       | `6`           |
| `KAFKA_CONSUMER_THREADS_NOTIFYPARENT`            | Number of threads for notifying when a subprocess is blocked          | `6`           |
| `KAFKA_CONSUMER_THREADS_ADAPTERS`                | Number of threads for processing messages related to adapters         | `6`           |
| `KAFKA_CONSUMER_THREADS_SCHEDULERADVANCING`      | Number of threads for continuing advancement                          | `6`           |
| `KAFKA_CONSUMER_THREADS_SCHEDULERRUNACTION`      | Number of threads for running scheduled actions                       | `6`           |
| `KAFKA_CONSUMER_THREADS_MESSAGEEVENTS`           | Number of threads for message events                                  | `6`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_START`           | Number of threads for starting processes                              | `6`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_STARTFOREVENT`   | Number of threads for starting processes for an event                 | `2`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_EXPIRE`          | Number of threads for expiring processes                              | `6`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_OPERATIONS`      | Number of threads for processing operations from task management      | `6`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_BATCHPROCESSING` | Number of threads for processing bulk operations from task management | `6`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE`    | Number of threads for processing UI flow session variable updates     | `6`           |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWEXPIRE`    | Number of threads for processing UI flow session expiry triggers      | `6`           |

All events that start with a configured pattern will be consumed by the Engine. This enables you to create new integrations and connect them to the engine without changing the configuration.

#### Configuring Kafka topics

##### Topic naming configuration

| Environment Variable                           | Description                         | Default Value          |
| ---------------------------------------------- | ----------------------------------- | ---------------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`                   | Package prefix for topic names      | `ai.flowx.`            |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT`               | Environment segment for topic names | ` `                    |
| `KAFKA_TOPIC_NAMING_VERSION`                   | Version suffix for topic names      | `.v1`                  |
| `KAFKA_TOPIC_NAMING_SEPARATOR`                 | Primary separator for topic names   | `.`                    |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`                | Secondary separator for topic names | `-`                    |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN`      | Engine receive pattern              | `engine.receive.`      |
| `KAFKA_TOPIC_NAMING_INTEGRATIONRECEIVEPATTERN` | Integration receive pattern         | `integration.receive.` |

##### Core engine topics

| Environment variable                 | Description                                               | Default value                             |
| ------------------------------------ | --------------------------------------------------------- | ----------------------------------------- |
| `KAFKA_TOPIC_PROCESS_NOTIFY_ADVANCE` | Topic used internally for advancing processes             | `ai.flowx.core.notify.advance.process.v1` |
| `KAFKA_TOPIC_PROCESS_NOTIFY_PARENT`  | Topic used for sub-processes to notify the parent process | `ai.flowx.core.notify.parent.process.v1`  |
| `KAFKA_TOPIC_PATTERN`                | Pattern the Engine listens on for incoming events         | `ai.flowx.engine.receive.*`               |
| `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE`  | Topic for process message events                          | `ai.flowx.core.message.event.process.v1`  |

##### Topics related to the Task Management plugin

| Environment variable                    | Description                                                | Default value                                |
| --------------------------------------- | ---------------------------------------------------------- | -------------------------------------------- |
| `KAFKA_TOPIC_TASK_OUT`                  | Topic used for sending notifications to the plugin         | `ai.flowx.plugin.tasks.trigger.save.task.v1` |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_IN`     | Topic for receiving information about operations performed | `ai.flowx.core.trigger.operation.v1`         |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_BULKIN` | Topic where operations can be performed in bulk            | `ai.flowx.core.trigger.operations.bulk.v1`   |

##### Topics related to the Notification plugin

| Environment variable     | Description                                                        | Default value                                               |
| ------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------- |
| `KAFKA_NOTIFICATION_OUT` | Topic for sending notification requests to the Notification plugin | `ai.flowx.plugin.notification.trigger.send.notification.v1` |

<Info>
  The `KAFKA_NOTIFICATION_OUT` topic must resolve to the same value as `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` in the Notification plugin configuration.
</Info>

##### Topics related to the Document plugin

The process-engine receives results from document-plugin operations on topics matching the pattern `ai.flowx.engine.receive.plugin.document.*`. The following topics are used for file encryption and decryption operations:

| Topic name                                                        | Description                                                      |
| ----------------------------------------------------------------- | ---------------------------------------------------------------- |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Topic for receiving file encryption results from document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Topic for receiving file decryption results from document-plugin |

<Info>
  These topics are automatically matched by the Engine's `KAFKA_TOPIC_PATTERN` configuration (default: `ai.flowx.engine.receive.*`). No additional configuration is required. The topics must be created in your Kafka infrastructure before deployment.
</Info>

###### OPERATIONS\_IN request example

```json theme={"system"}
{
  "operationType": "UNASSIGN", //type of operation performed in Task Management plugin
  "taskId": "some task id",
  "processInstanceUuid": "1cff0b7d-966b-4b35-9e9b-63b1d6757ec6",
  "swimlaneName": "Default",
  "swimlaneId": "51ec1241-fe06-4576-9c84-31598c05c527",
  "owner": {
    "firstName": null,
    "lastName": null,
    "username": "service-account-flowx-process-engine-account",
    "enabled": false
  },
  "author": "admin@flowx.ai"
}
```

###### BULK\_IN request example

```json theme={"system"}
{
  "operations": [
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223", // the id of the process instance
      "swimlaneName": "Default", //name of the swimlane
      "owner": null,
      "author": "john.doe@flowx.ai"
    },
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default", //name of the swimlane
      "owner": null,
      "author": "john.doe@flowx.ai"
    }
  ]
}      
```

<Info>
  To send additional keys in the response, attach them in the header. For example, you can use a `requestID` key.
</Info>

<Check>
  A response should be sent on a `callbackTopic` if it is mentioned in the headers:

  <Frame>
    ![Callback topic with requestID header example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/bulk_requestid.png)
  </Frame>

  ```json theme={"system"}
  {"processInstanceId": ${processInstanceId}, "callbackTopic": "test.operations.out", "requestID":"1234567890"}
  ```
</Check>

<Info>
  Process operations on this topic include: assignment, unassignment, hold, unhold, terminate. The Task Manager produces the assignment and hold operations on its `...operations.out` topic; terminate is available only to direct Kafka producers. For more information, see the Task Management plugin documentation:

  📄 [**Task management plugin**](../../docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
</Info>

##### Topics related to UI flow session updates

| Environment variable           | Description                                                                                                              | Default value                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates                                                                     | `ai.flowx.core.trigger.ui-flow.update.v1` |
| `KAFKA_TOPIC_UIFLOW_EXPIRE_IN` | Topic for receiving UI flow session expiry triggers, published by scheduler-core when a session's expiry time is reached | `ai.flowx.core.trigger.expire.ui-flow.v1` |

##### Topics related to runtime config params

<Info>
  **Available starting with FlowX.AI 5.9.1**
</Info>

| Environment variable                 | Description                                                                                                         | Default value                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | Topic for receiving runtime config-param change events from Application Manager, used to invalidate the build cache | `ai.flowx.config.params.events.v1` |

When a runtime config param is created, updated, or deleted, Application Manager publishes a change event to this topic. The Engine consumes it and clears the cached build configuration for the affected `workspaceId` and `appVersionId`, then broadcasts the invalidation to its other replicas through a Redis pub/sub channel:

| Environment variable                     | Description                                                                                    | Default value                 |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------- |
| `FLOWX_CONFIGPARAMS_EVENTS_REDISCHANNEL` | Redis pub/sub channel used to propagate config-param cache invalidation across Engine replicas | `config-params-redis-channel` |

##### Topics related to the scheduler extension

| Environment variable                         | Description                                              | Default value                              |
| -------------------------------------------- | -------------------------------------------------------- | ------------------------------------------ |
| `KAFKA_TOPIC_PROCESS_EXPIRE_IN`              | Topic for requests to expire processes                   | `ai.flowx.core.trigger.expire.process.v1`  |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET`       | Topic used for scheduling process expiration             | `ai.flowx.core.trigger.set.schedule.v1`    |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP`      | Topic used for stopping process expiration               | `ai.flowx.core.trigger.stop.schedule.v1`   |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_IN_RUN_ACTION` | Topic for requests to run scheduled actions              | `ai.flowx.core.trigger.run.action.v1`      |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_IN_ADVANCE`    | Topic for events related to advancing through a database | `ai.flowx.core.trigger.advance.process.v1` |

##### Topics related to Timer Events

| Environment variable                                | Description                                     | Default value                                        |
| --------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET`  | Used to communicate with Scheduler microservice | `ai.flowx.core.trigger.set.timer-event-schedule.v1`  |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Used to communicate with Scheduler microservice | `ai.flowx.core.trigger.stop.timer-event-schedule.v1` |

##### Topics related to the Search Data service

| Environment variable          | Description                                               | Default value                                         |
| ----------------------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| `KAFKA_TOPIC_DATA_SEARCH_IN`  | Topic that the Engine listens on for search requests      | `ai.flowx.core.trigger.search.data.v1`                |
| `KAFKA_TOPIC_DATA_SEARCH_OUT` | Topic used by the Engine to reply after finding a process | `ai.flowx.engine.receive.core.search.data.results.v1` |

##### Topics related to the Audit service

| Environment variable    | Description                  | Default value                         |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

##### Topics related to Elasticsearch indexing

| Environment variable            | Default value                    |
| ------------------------------- | -------------------------------- |
| `KAFKA_TOPIC_PROCESS_INDEX_OUT` | `ai.flowx.core.index.process.v1` |

##### Processes that can be started by sending messages to a Kafka topic

| Environment variable            | Description                                                       | Default value                            |
| ------------------------------- | ----------------------------------------------------------------- | ---------------------------------------- |
| `KAFKA_TOPIC_PROCESS_START_IN`  | Topic for requests to start a new process instance                | `ai.flowx.core.trigger.start.process.v1` |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for sending the reply after starting a new process instance | `ai.flowx.core.confirm.start.process.v1` |

##### Topics related to Message Events

| Environment variable                | Default value                                      |
| ----------------------------------- | -------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT` | `ai.flowx.core.trigger.start-for-event.process.v1` |
|                                     |                                                    |

##### Topics related to Events-gateway microservice

| Environment variable                       | Description                                               | Default value                                          |
| ------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------ |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE`    | Outgoing messages from process-engine to events-gateway   | `ai.flowx.eventsgateway.engine.commands.message.v1`    |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_DISCONNECT` | Disconnect commands from process-engine to events-gateway | `ai.flowx.eventsgateway.engine.commands.disconnect.v1` |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_CONNECT`    | Connect commands from process-engine to events-gateway    | `ai.flowx.eventsgateway.engine.commands.connect.v1`    |

##### Topics related to platform components

| Environment variable                           | Description                        | Default value                                        |
| ---------------------------------------------- | ---------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_PLATFORM_COMPONENTS_VERSIONS_OUT` | Topic for platform version caching | `ai.flowx.core.trigger.platform.versions.caching.v1` |

##### Inter-service topic coordination

When configuring FlowX services, ensure the following:

1. The Engine's `pattern` must match the pattern used by services sending messages to the Engine
2. The `integrationPattern` must match the pattern used by the Integration Designer
3. Output topics from one service must match the expected input topics of another service

For example:

* Services send to topics matching `ai.flowx.engine.receive.*` → Engine listens
* Engine sends to topics matching `ai.flowx.integration.receive.*` → Integration Designer listens

##### Kafka message size configuration

| Environment variable      | Description                   | Default value     |
| ------------------------- | ----------------------------- | ----------------- |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size in bytes | `52428800` (50MB) |

This setting affects:

* Producer message max bytes
* Producer max request size
* Consumer max partition fetch bytes

##### Kafka authentication (when using SASL\_PLAINTEXT)

For secure environments, enable OAuth authentication with the following environment variables:

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Configuring Elasticsearch connection

The Process Engine uses Elasticsearch for process instance indexing and search capabilities. Configure the connection using these environment variables:

| Variable                               | Description                                 | Default Value |
| -------------------------------------- | ------------------------------------------- | ------------- |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL`   | Connection protocol                         | `https`       |
| `SPRING_ELASTICSEARCH_REST_URIS`       | URL(s) of Elasticsearch nodes (no protocol) | -             |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL` | Disable SSL verification                    | `false`       |
| `SPRING_ELASTICSEARCH_REST_USERNAME`   | Authentication username                     | -             |
| `SPRING_ELASTICSEARCH_REST_PASSWORD`   | Authentication password                     | -             |

<Info>
  For indexing setup, check the [Configuring Elasticsearch indexing](./configuring-elasticsearch-indexing/elasticsearch-indexing) section.
</Info>

#### Indexing settings

| Variable                                     | Description                                       | Default Value      |
| -------------------------------------------- | ------------------------------------------------- | ------------------ |
| `FLOWX_INDEXING_ENABLED`                     | Enable/disable indexing globally                  | `true`             |
| `FLOWX_INDEXING_TYPE`                        | Indexing strategy (http, kafka, no-indexing)      | `http`             |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME`     | Name of the Elasticsearch index                   | `process_instance` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS`   | Number of primary shards                          | `2`                |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | Number of replica shards                          | `0`                |
| `FLOWX_INDEXING_OPTIMISTICLOCKINGRETRIES`    | Retry attempts for optimistic locking (HTTP only) | `3`                |

### Configuring file upload size

| Environment variable                      | Description                              | Default value |
| ----------------------------------------- | ---------------------------------------- | ------------- |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE`    | Maximum file size allowed for uploads    | `50MB`        |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size allowed for uploads | `50MB`        |

#### Connecting the Advancing controller

To use the advancing controller, configure the following variables:

| Environment variable                   | Description                                                                                                                                                                                 | Default value                                 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `ADVANCING_DATASOURCE_URL`             | Connection URL for Advancing Postgres DB                                                                                                                                                    | `jdbc:postgresql://postgresql:5432/advancing` |
| `ADVANCING_DATASOURCE_USERNAME`        | Username for Advancing DB connection                                                                                                                                                        | `flowx`                                       |
| `ADVANCING_DATASOURCE_PASSWORD`        | Password for Advancing DB connection                                                                                                                                                        | `-`                                           |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | Maximum size of the advancing datasource connection pool. Worker threads open their own connections, configured separately via `ADVANCING_PICKINGTHREADS` and `ADVANCING_PROCESSINGTHREADS` | `20`                                          |

#### Configuring the Advancing controller

| Environment variable                           | Description                                                                      | Default value                                  |
| ---------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- |
| `ADVANCING_TYPE`                               | Type of advancing mechanism                                                      | `PARALLEL` (alternatives: `KAFKA`, `PARALLEL`) |
| `ADVANCING_PICKINGTHREADS`                     | Number of worker threads for reading from database (picking operations)          | `1`                                            |
| `ADVANCING_PROCESSINGTHREADS`                  | Number of threads for parallel processing of advancing events                    | `20`                                           |
| `ADVANCING_PROCESSINGBUFFERSIZE`               | Maximum buffer size for processing queue. Controls how many events can be queued | `20`                                           |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`    | Block picking operations when no worker threads are available                    | `true`                                         |
| `ADVANCING_PICKINGPAUSEMILLIS`                 | Pause duration between picking batches (ms)                                      | `50`                                           |
| `ADVANCING_COOLDOWNAFTERSECONDS`               | Cooldown period after processing a batch (seconds)                               | `120`                                          |
| `ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION` | Cron expression for the heartbeat                                                | `"*/2 * * * * ?"`                              |

<Info>
  **How the new advancing controller works:**

  * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.

  * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space (even just 1 position), that amount of events will be read.

  * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.

  * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.
</Info>

<Card title="Advancing controller setup" href="../advancing-controller-setup-guide" icon="gears" />

### CAS lib configuration

| Environment Variable  | Description                  | Default Value |
| --------------------- | ---------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | -             |

### Configuring cleanup mechanism

| Environment variable                      | Description                                       | Default value                                              |
| ----------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `SCHEDULER_THREADS`                       | Number of threads for the scheduler               | `10`                                                       |
| `SCHEDULER_PROCESSCLEANUP_ENABLED`        | Activates the cron job for process cleanup        | `false`                                                    |
| `SCHEDULER_PROCESSCLEANUP_CRONEXPRESSION` | Cron expression for the process cleanup scheduler | `0 */5 0-5 * * ?` (every 5 minutes between 12 AM and 5 AM) |
| `SCHEDULER_PROCESSCLEANUP_BATCHSIZE`      | Number of processes to clean up in one batch      | `1000`                                                     |

### Managing subprocesses expiration

| Environment variable               | Description                                                                                                                                 | Default value |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_PROCESS_EXPIRESUBPROCESSES` | When true, terminates all subprocesses upon parent process expiration. When false, subprocesses follow their individual expiration settings | `true`        |

### Configuring application management

<Warning>
  The following configuration from versions before 4.1 will be deprecated in version 5.0:

  * `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED`: Enables or disables Prometheus metrics export.
</Warning>

<Info>
  Starting from version 4.1, use the following configuration instead. This setup is backwards compatible until version 5.0.
</Info>

| Environment variable                           | Description                       | Default value |
| ---------------------------------------------- | --------------------------------- | ------------- |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enables Prometheus metrics export | `false`       |

***

## RBAC configuration

Process Engine requires specific RBAC permissions for proper access to Kubernetes resources:

```yaml theme={"system"}
rbac:
  create: true
  rules:
    - apiGroups:
        - ""
      resources:
        - secrets
        - configmaps
        - pods
      verbs:
        - get
        - list
        - watch
```

***

## Ingress and CORS

The Process Engine is exposed on both the admin and public hosts, with a dedicated route for runtime process instances on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group      | External path     | Backend receives     | Notes               |
| --------------- | ----------------- | -------------------- | ------------------- |
| admin           | `/onboarding/api` | `/api/...`           | Strip `/onboarding` |
| public          | `/onboarding/api` | `/api/...`           | Strip `/onboarding` |
| admin-instances | `/api/instances`  | `/api/instances/...` | Path preserved      |

Paths are set through `services.process-engine.ingress.<key>.path` (or `gateway.<key>.paths`) in the chart values. The admin and public routes share the same backend route family — the `/onboarding` prefix is stripped before forwarding so the backend receives `/api/...`.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                   | Default Value |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Process Engine. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](../ingress-configuration).

<Info>
  For SSE (Server-Sent Events) communication configuration, refer to the [Events Gateway setup](../events-gateway-setup) guide.
</Info>

***

### Script engine configuration

The process engine uses a native script engine for executing JavaScript and Python business rules. The native engine runs scripts in separate Node.js and Python worker processes.

| Environment variable                                                  | Description                                    | Default value    |
| --------------------------------------------------------------------- | ---------------------------------------------- | ---------------- |
| `APPLICATION_SCRIPTENGINE_PROVIDER`                                   | Script engine provider (`native` or `graalvm`) | `native`         |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE`                   | Number of Node.js worker processes             | `16`             |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS`         | Execution timeout per script (ms)              | `5000`           |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER`     | Max executions before a worker is recycled     | `10000`          |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES`        | Max input payload size (bytes)                 | `1048576` (1 MB) |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE`               | Number of Python worker processes              | `8`              |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`     | Execution timeout per script (ms)              | `10000`          |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a worker is recycled     | `10000`          |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES`    | Max input payload size (bytes)                 | `1048576` (1 MB) |

<Info>
  The `native` script engine is the default starting with 5.9.0, replacing the previous GraalVM-based engine. Scripts run in isolated subprocess pools. To revert to GraalVM, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`.
</Info>

### Stuck token recovery

Automatically recovers process tokens that get stuck due to transient failures.

| Environment variable                            | Description                                            | Default value   |
| ----------------------------------------------- | ------------------------------------------------------ | --------------- |
| `SCHEDULER_STUCKTOKENRECOVERY_ENABLED`          | Turn on or off stuck token recovery                    | `false`         |
| `SCHEDULER_STUCKTOKENRECOVERY_CRONEXPRESSION`   | Cron expression for recovery sweeps                    | `0 */5 * * * ?` |
| `SCHEDULER_STUCKTOKENRECOVERY_THRESHOLDMINUTES` | Minutes a token must be stuck before recovery triggers | `10`            |
| `SCHEDULER_STUCKTOKENRECOVERY_BATCHSIZE`        | Max tokens recovered per sweep                         | `100`           |
| `SCHEDULER_STUCKTOKENRECOVERY_MAXAGEHOURS`      | Max age (hours) of stuck tokens to consider            | `4`             |

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Engine fails to start">
    **Symptoms:** The process-engine pod crashes or restarts repeatedly during startup.

    **Solutions:**

    1. Verify PostgreSQL connectivity and that the database exists and is accessible
    2. Check Redis connection settings (`SPRING_REDIS_HOST`, `SPRING_REDIS_PORT`) and ensure Redis is running
    3. Confirm Kafka bootstrap servers are reachable (`SPRING_KAFKA_BOOTSTRAPSERVERS`)
    4. Review pod logs for specific connection errors — the first failing dependency is usually the root cause
    5. Ensure all required secrets (database passwords, OAuth credentials) are correctly mounted
  </Accordion>

  <Accordion title="Process instances not advancing">
    **Symptoms:** Processes get stuck at certain nodes and do not move forward.

    **Solutions:**

    1. Verify the advancing controller is running and properly connected (`ADVANCING_DATASOURCE_JDBC_URL`)
    2. Check that advancing-related Kafka topics exist and are correctly configured (`KAFKA_TOPIC_PROCESS_NOTIFY_ADVANCE`)
    3. Review the advancing controller type (`ADVANCING_TYPE`) and thread configuration
    4. Ensure the scheduler extension topics are properly set up for timer-based advances
    5. Check Kafka consumer group lag for `advance` and `scheduler-advancing` groups
  </Accordion>

  <Accordion title="Elasticsearch indexing not working">
    **Symptoms:** Process instances are not appearing in search results or the indexing service reports errors.

    **Solutions:**

    1. Confirm `FLOWX_INDEXING_ENABLED` is set to `true`
    2. Verify Elasticsearch connection settings (`SPRING_ELASTICSEARCH_REST_URIS`, credentials)
    3. Check that the indexing type matches your setup (`FLOWX_INDEXING_TYPE`: `kafka` or `http`)
    4. If using Kafka indexing, ensure the `KAFKA_TOPIC_PROCESS_INDEX_OUT` topic exists
    5. Verify the Elasticsearch index name and shard configuration are valid
  </Accordion>

  <Accordion title="High memory usage">
    **Symptoms:** The process-engine pod experiences OOM kills or high memory consumption.

    **Solutions:**

    1. Review Redis caching configuration — large process definitions and compiled scripts are cached in Redis
    2. Check `ADVANCING_PROCESSINGBUFFERSIZE` and `ADVANCING_PROCESSINGTHREADS` — high values increase memory usage
    3. Ensure the cleanup mechanism is enabled (`SCHEDULER_PROCESSCLEANUP_ENABLED`) to remove completed process instances
    4. Review Kafka consumer thread counts — each thread consumes memory for message buffering
    5. Monitor the config params cache settings (`FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`) and reduce if needed
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Redis Configuration" icon="database" href="../redis-configuration">
    Cache and session configuration including Sentinel and Cluster modes
  </Card>

  <Card title="Elasticsearch Indexing" icon="magnifying-glass" href="./configuring-elasticsearch-indexing/elasticsearch-indexing">
    Configure process instance indexing and search capabilities
  </Card>

  <Card title="Process Instance Archiving" icon="box-archive" href="./process-instance-data-archiving">
    Archive and manage historical process instance data
  </Card>

  <Card title="Access Roles for Processes" icon="user-lock" href="./configuring-access-roles-for-processes">
    Configure role-based access control for process definitions
  </Card>
</CardGroup>


# Partitioning & archiving
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving

Improving data management using data partitioning and the archival processes.

## Overview

<Tip>
  You can enable data partitioning on the FlowX.AI Engine.
</Tip>

Partitioning and archiving are data management strategies used to handle large volumes of data efficiently. They improve database performance, manageability, and storage optimization. By dividing data into partitions and archiving older or less frequently accessed data, organizations can ensure better data management, quicker query responses, and optimized storage use.

## Partitioning

Partitioning is the process of dividing a large database table into smaller, more manageable pieces, called partitions. Each partition can be managed and queried independently. The primary goal is to improve performance, enhance manageability, and simplify maintenance tasks such as backups and archiving.

Partitions can be created per day, week or month. This means that a partition ID is computed at insert time for each row of process\_instance and related tables.

Afterwards, a retention period can be setup (eg: 3 partitions). A flowx engine-driven cron job (with configurable start interval) will check if there is any partition which needs to be archived and will perform the necessary actions.

### Benefits of partitioning

* **Improved Query Performance**: By scanning only relevant partitions instead of the entire table.
* **Simplified Maintenance**: Easier to perform maintenance tasks like backups and index maintenance.
* **Data Management**: Better data organization and management by dividing data based on specific criteria such as date, range, or list.

<Info>
  Database Compatibility: Oracle Database and PostgreSQL.
</Info>

## Archiving

Archiving involves moving old data from the primary tables to separate archive tables. This helps in reducing the load on the primary tables, thus improving performance and manageability.

### Benefits of archiving

* **Storage Optimization**: Archived data can be compressed, saving storage space.
* **Performance Improvement**: Reduces the volume of data in primary tables, leading to faster query responses.
* **Historical Data Management**: Maintains historical data in a separate, manageable form.

## Partitioning and archiving in Oracle Database

### Oracle Database partitioning

<Steps>
  <Step title="Concept">
    Oracle Database [**partitioned tables**](https://docs.oracle.com/en/database/oracle/oracle-database/18/vldbg/partition-concepts.html#GUID-6D369646-16AF-487B-BF32-5F6569D27C8A) are utilized, allowing for efficient data management and query performance.
  </Step>

  <Step title="Implementation">
    Each partition can be managed and queried independently.

    Example: The `process_instance` table can be partitioned by day, week, or month.
  </Step>

  <Step title="Benefits">
    Improved query performance by scanning only relevant partitions.

    Simplified maintenance tasks like backups and archiving.
  </Step>
</Steps>

### Oracle Database archiving

<Steps>
  <Step title="Process">
    Detaching the partition from the main table.

    Converting the detached partition into a new table named `archived_${table_name}_${interval_name}_${reference}` for example: `archived_process_instance_monthly_2024_03` .

    <Info>
      The DATE is in the format `yyyy-MM-dd` if the interval is `DAY`, or in the format `yyyy-MM` if the interval is `MONTH`, or in the format `yyyy-weekOfYear` if the interval is `WEEK`.
    </Info>
  </Step>

  <Step title="Steps">
    Identify partitions eligible for archiving based on retention settings.

    Detach the partition from the main table.

    Create a new table with the data from the detached partition.

    Optionally compress the new table to save space.
  </Step>

  <Step title="Benefits">
    Manages historical data by moving it to separate tables, reducing the load on the main table.

    Compression options (OFF, BASIC, ADVANCED) further optimize storage.

    <Info>
      Oracle offers several compression options—OFF, BASIC, and ADVANCED—that optimize storage. Each option provides varying levels of data compression, impacting storage savings and performance differently.

      * **OFF**: No compression is applied.
      * **BASIC**: Suitable for read-only or read-mostly environments, it compresses data without requiring additional licenses.
      * **ADVANCED**: Offers the highest level of compression, supporting a wide range of data types and operations. It requires an Advanced Compression license and provides significant storage savings and performance improvements by keeping data compressed in memory.

      For more details, you can refer to Oracle's [**Advanced Compression documentation**](https://www.oracle.com/database/advanced-compression/#rc30related).
    </Info>
  </Step>
</Steps>

## PostgreSQL archiving

<Steps>
  <Step title="Process">
    Creating a new table for the partition being archived.

    Moving data from the main table to the new archive table (in batches).

    <Info>
      Since here the DB has more work to do than just changing some labels (actual data insert and delete vs relabel a partition into a table, for Oracle Database) the data move is batched and the batch size is configurable.
    </Info>
  </Step>

  <Step title="Steps">
    Identify partitions eligible for archiving based on retention settings.

    Create a new table following this naming convention: `archived__${table_name}__${interval_name}_${reference}`, example: *archived\_\_process\_instance\_\_weekly\_2024\_09* .

    <Tip>
      The new table is created (same name format as for Oracle Database: `archived__${table_name}__${interval_name}_${reference}`) and data is moved from the primary table here.
    </Tip>

    Configure the batch size for data movement to control the load on the database.
  </Step>

  <Step title="Benefits">
    Efficiently manages historical data.

    Batch processing allows for better control over the archiving process and system performance.
  </Step>
</Steps>

<Info>
  Differences from Oracle DBs:

  Archiving involves actual data movement (insert and delete operations), unlike Oracle Databases where it is mainly a relabeling of partitions.

  The batch size for data movement is configurable, allowing fine-tuning of the archiving process.
</Info>

## Daily operations

Once set up, the partitioning and archiving process involves the following operations:

<Steps>
  <Step title="Partition ID Calculation">
    The `partition_id` is automatically calculated based on the configured interval (DAY, WEEK, MONTH).
    Example for daily partitioning: `2024-03-01 13:00:00` results in `partition_id = 124061`. See the [**Partition ID calculation**](#partition-id-calculation) section.
  </Step>

  <Step title="Retention Management">
    Data older than the configured retention interval becomes eligible for archiving and compressing.
  </Step>

  <Step title="Archiving process">
    A cron job checks for eligible partitions.

    Eligible partitions are archived and optionally compressed.

    The process includes deactivating foreign keys, creating new archive tables, moving data references, reactivating foreign keys, and dropping the original partition.
  </Step>

  <Step title="Space management">
    Archived tables remain in the database but occupy less space if compression is enabled.

    **Recommendation**: to free up space, consider moving archived tables to a different database or tablespace. Additionally, you have the option to move only process instances or copy definitions depending on your needs.
  </Step>
</Steps>

<Warning>
  When enabling partitioning, please consider the following:

  **Ensure Process Termination**: Make sure that process instances get terminated. Archiving removes process instance data from the working data, making it not available in FlowX. Started instances should be finished before archiving takes place.

  **Set Process Expiry**: To ensure termination of process instances prior to archiving, it is recommended to configure process expiration. Refer to the following section for guidance on setting up process expiry using FlowX Designer:

  [Timer Expressions](../../docs/building-blocks/node/timer-events/timer-expressions)
</Warning>

<Info>
  Future schema updates or migrations will not affect archived tables. They retain the schema from the moment of archiving.
</Info>

## Configuring partitioning and archiving

<Info>
  The Partitioning and Archiving feature is optional and can be configured as needed.
</Info>

<Tip>
  When starting a new version of the process-engine, we recommend manually executing the setup SQL commands from Liquibase, as they may take more time. After setup, all existing information will go into the initial partition.
</Tip>

Partitioning and archiving are configured under the `flowx.data.partitioning` block on the process-engine. Archiving settings — including the scheduler that detaches and archives old partitions — live in the nested `archiving` block:

```yaml theme={"system"}
flowx:
  data:
    partitioning:
      enabled: false        # master switch for data partitioning
      interval: MONTH        # DAY, WEEK, MONTH
      archiving:
        enabled: false       # runs the cron job that detaches and archives old partitions
        cronExpression: "0 0 1 * * ?"   # daily at 01:00
        retention-intervals: 3          # intervals kept in the FlowX database before archiving
        detached-partition-compression: OFF   # OFF, BASIC, ADVANCED (Oracle only)
        moved-data-batch-size: 5000           # PostgreSQL only
```

The equivalent environment variables:

| Environment Variable                                             | Description                                                          | Default Value                  | Possible Values                       |
| ---------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------ | ------------------------------------- |
| `FLOWX_DATA_PARTITIONING_ENABLED`                                | Master switch for data partitioning.                                 | `false`                        | `true`, `false`                       |
| `FLOWX_DATA_PARTITIONING_INTERVAL`                               | Interval contained in a partition.                                   | `MONTH`                        | `DAY`, `WEEK`, `MONTH`                |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`                      | Runs the cron job that detaches and archives old partitions.         | `false`                        | `true`, `false`                       |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`               | Cron expression for the archiving scheduler.                         | `0 0 1 * * ?` (daily at 01:00) | Cron expression                       |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`           | Number of intervals retained in the FlowX database before archiving. | `3`                            | Integer values (e.g., `1`, `2`, `3`)  |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHEDPARTITIONCOMPRESSION` | Compression for archived (detached) partitions (Oracle only).        | `OFF`                          | `OFF`, `BASIC`, `ADVANCED`            |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVEDDATABATCHSIZE`           | Batch size for moving data (PostgreSQL only).                        | `5000`                         | Integer values (e.g., `1000`, `5000`) |

<Warning>
  **Upgrading from 5.1.x?** The configuration changed. The standalone `SCHEDULER_DATA_PARTITIONING_ENABLED` and `SCHEDULER_DATA_PARTITIONING_CRON_EXPRESSION` variables no longer exist — the archiving scheduler now lives under `flowx.data.partitioning.archiving`. The archiving scheduler also defaults to **off** (`archiving.enabled: false`), whereas the old scheduler defaulted to on. See [FlowX Engine partitioning migration](/5.9/migrating-from-5.1-lts/engine-partitioning) for the full mapping.
</Warning>

<Info>
  Compression for archived (detached) partitions is available only for Oracle DBs.
</Info>

<Info>
  The batch size setting for archiving data is available only for PostgreSQL DBs.
</Info>

## Logging information

Partitioning and archiving actions are logged in two tables:

* `DATA_PARTITIONING_LOG`: For tracking archived partitions.

<Frame>
  ![Data partitioning log table](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/partitioning_log.png)
</Frame>

* `DATA_PARTITIONING_LOG_ENTRY`: For logging SQL commands executed for archiving.

<Frame>
  ![Data partitioning log entry table](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/partitioning_log_entry.png)
</Frame>

## Enabling partitioning and Elasticsearch indexing strategy

When partitioning is enabled, the Elasticsearch indexing strategy must also be enabled and configured on FlowX Engine setup.

<Card icon="info">
  **Why?**

  * When archiving process instances, data from Elasticsearch must be deleted, not just the cache but also indexed keys (e.g., those indexed for data search on process instances).
</Card>

### Elasticsearch indexing configuration

Check the Elasticsearch indexing setup here:

<Card title="Elasticsearch indexing setup" href="./configuring-elasticsearch-indexing/" icon="link" />

The partitioning configuration must be aligned with the configuration extracted from the Kafka Elasticsearch Connector, especially with the following environment variables, so the intervals are similar:

### Index partitioning

* `transforms.routeTS.topic.format: "process_instance-${timestamp}"`: This value must start with the index name defined in the process-engine config: flowx.indexing.processInstance.index-name. In this example, the index name is prefixed with "process\_instance-" and appended with a timestamp for dynamic index creation. For backward compatibility, the prefix must be "process\_instance-". However, backward compatibility is not strictly required here.
  yaml

* `transforms.routeTS.timestamp.format: "yyyyMMdd"`: This format ensures that timestamps are consistently represented and easily parsed when creating or searching for indices based on the process instance start date. You can adjust this value as needed (e.g., for monthly indexes, use "yyyyMM"). However, note that changing this format will cause existing indexed objects to remain unchanged, and update messages will be treated as new objects, indexed again in new indices. It is crucial to determine your index size and maintain consistency.

Check the following Kafka Elasticsearch Connector configuration example for more details:

<Card title="Kafka Elasticsearch Connector" href="./configuring-elasticsearch-indexing/elasticsearch-indexing#kafka-elasticsearch-connector" icon="link" />

## Technical details

### Partition ID calculation

* The `partition_id` format follows this structure: `<LEVEL || YEAR || BIN_ID_OF_YEAR>`. This ID is calculated based on the start date of the `process_instance`, the partition interval, and the partition level.
  * `LEVEL`: This represents the "Partitioning level," which increments with each change in the partitioning interval (for example, if it changes from `DAY` to `MONTH` or vice versa).
  * `YEAR`: The year extracted from the `process_instance` date.
  * `BIN_ID_OF_YEAR`: This is the ID of a bucket associated with the `YEAR`. It is created for all instances within the selected partitioning interval. The maximum number of buckets is determined by the partitioning frequency:
    * **Daily**: Up to 366 buckets per year
    * **Weekly**: Up to 53 buckets per year
    * **Monthly**: Up to 12 buckets per year

#### Calculation example

For a timestamp of `2024-03-01 13:00:00` with a daily partitioning interval, the `partition_id`would be `124061`:

* `1`: Partitioning Level (`LEVEL`)
* `24`:  Year - 2024 (`YEAR`)
* `061`: Bucket per configuration (61st day of the year)

### Archived tables

* Naming format: `archived__${table_name}__${interval_name}_${reference}`. Examples:
  * archived\_\_process\_instance\_\_monthly\_2024\_03
  * archived\_\_process\_instance\_\_weekly\_2024\_09
  * archived\_\_process\_instance\_\_daily\_2024\_03\_06


# Routing
Source: https://docs.flowx.ai/5.9/setup-guides/ingress-configuration

How FlowX services are exposed externally on 5.9.x, the per-service route table, and CORS handling at the application layer.

This guide describes how external traffic reaches FlowX services on 5.9.x: the two-host model (admin and public), the per-service route table, and CORS handling per deployment.

## Overview

On 5.9.x, FlowX services are exposed through either Kubernetes Ingress resources (the default) or Gateway API HTTPRoutes, with each service toggled independently. CORS handling moved out of ingress annotations and into the service code, with allowed origins set via an environment variable on each backend service.

Two things changed in 5.9.x compared to 5.1.x routing:

1. **Gateway API HTTPRoutes** are available as an opt-in alternative to Kubernetes Ingress. Switching a service to HTTPRoute mode is coordinated with FlowX during the upgrade window and requires the Gateway API CRDs (`gateway.networking.k8s.io/v1`) plus a compatible controller on the cluster.
2. **CORS moves to the application layer.** NGINX CORS annotations are no longer the source of truth. Each backend service reads its allowed origins from `APPLICATION_CORS_ALLOWORIGIN`; allowed methods, headers, and credentials are baked into each service's `application.yaml` with sensible defaults.

For the migration path from 5.1.x to 5.9.x, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

***

## Service route reference

FlowX services route under two host groups: **admin** (designer and admin-side APIs) and **public** (runtime renderer and integration callers). A few services additionally use a third group called **admin-instances** for runtime instance APIs on the admin host.

### Admin routes

| Service                  | External path         | Backend receives                   |
| ------------------------ | --------------------- | ---------------------------------- |
| `admin`                  | `/`                   | `/`                                |
| `application-manager`    | `/appmanager`         | `/`                                |
| `audit-core`             | `/audit`              | `/`                                |
| `authorization-system`   | `/auth`               | `/`                                |
| `cms-core`               | `/cms`                | `/`                                |
| `document-plugin`        | `/document`           | `/`                                |
| `events-gateway`         | `/api/events`         | `/api/events/...` (path preserved) |
| `integration-designer`   | `/integration`        | `/`                                |
| `license`                | `/license`            | `/`                                |
| `notification-plugin`    | `/notification`       | `/`                                |
| `organization-manager`   | `/org`                | `/`                                |
| `process-engine`         | `/onboarding/api`     | `/api/...`                         |
| `runtime-manager`        | `/rtm/api/build-mgmt` | `/api/build-mgmt/...`              |
| `task-management-plugin` | `/task`               | `/`                                |
| `webhook-gateway`        | `/webhooks`           | `/webhooks/...` (path preserved)   |

### Public routes

| Service                  | External path      | Backend receives                   |
| ------------------------ | ------------------ | ---------------------------------- |
| `cms-core`               | `/cms`             | `/`                                |
| `designer`               | `/`                | `/`                                |
| `document-plugin`        | `/document`        | `/`                                |
| `events-gateway`         | `/api/events`      | `/api/events/...` (path preserved) |
| `organization-manager`   | `/org`             | `/`                                |
| `process-engine`         | `/onboarding/api`  | `/api/...`                         |
| `runtime-manager`        | `/rtm/api/runtime` | `/api/runtime/...`                 |
| `task-management-plugin` | `/task`            | `/`                                |

The Designer also gets a wildcard host rule (`*.<public-host>`) for workspace-per-subdomain access; this is set up by FlowX and does not require additional configuration on your side.

### Admin-instances routes

A third group on the admin host carries runtime process and instance APIs:

| Service           | External path                                   | Backend receives                                |
| ----------------- | ----------------------------------------------- | ----------------------------------------------- |
| `process-engine`  | `/api/instances`                                | `/api/instances/...` (path preserved)           |
| `runtime-manager` | `/rtm/api/runtime`, `/rtm/api/runtime-internal` | `/api/runtime/...`, `/api/runtime-internal/...` |

### Internal-only services

The following services are not exposed externally and have no ingress or HTTPRoute rendered: `advancing-controller`, `data-search`, `email-gateway`, `nosql-db-runner`, `scheduler-core`.

***

## CORS configuration

CORS is handled inside each backend service rather than at the ingress layer. Only the allowed-origins list is deployment-specific; allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into each service's `application.yaml` with safe defaults.

### `APPLICATION_CORS_ALLOWORIGIN`

Set this environment variable on every backend service exposed via admin or public URLs:

```yaml theme={"system"}
env:
  APPLICATION_CORS_ALLOWORIGIN: "https://designer.yourcompany.com,https://*.yourcompany.com"
```

Wildcard subdomain patterns are supported. The variable must be set on each of the 15 backend services listed in [Service route reference](#service-route-reference); designer and other frontend-only services do not need it.

The per-service rows are listed in the [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#cors-handling-application_cors_alloworigin).

### Removed NGINX annotations

The following NGINX-specific annotations are no longer rendered on the default ingress templates and have no effect on 5.9.x:

* `nginx.ingress.kubernetes.io/enable-cors`
* `nginx.ingress.kubernetes.io/cors-allow-credentials`
* `nginx.ingress.kubernetes.io/cors-allow-headers`
* `nginx.ingress.kubernetes.io/cors-allow-methods`
* `nginx.ingress.kubernetes.io/cors-allow-origin`

Any leftover overrides referencing these should be removed during the upgrade.

***

## Customizing routes

Per-service annotations (proxy body size, timeouts, TLS, affinity, cert-manager wiring) are applied to the rendered Ingress through your deployment's chart values. Common customizations and how they map between Ingress mode and HTTPRoute mode:

| Customization              | Ingress mode (annotation)                                                 | HTTPRoute mode                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Proxy body size (uploads)  | `nginx.ingress.kubernetes.io/proxy-body-size: "50m"` (annotation-driven)  | Controller-specific policy CRD (Envoy Gateway `BackendTrafficPolicy`, Istio `EnvoyFilter`, Traefik `Middleware`) |
| Request timeouts           | `nginx.ingress.kubernetes.io/proxy-read-timeout`, `proxy-connect-timeout` | `spec.rules[].timeouts.request` on the HTTPRoute                                                                 |
| URL rewrite                | `nginx.ingress.kubernetes.io/rewrite-target`                              | `URLRewrite` filter on the HTTPRoute                                                                             |
| Session affinity           | `nginx.ingress.kubernetes.io/affinity: "cookie"`                          | Controller-specific (Gateway API `sessionPersistence` field, v1.1+)                                              |
| TLS certificate management | `cert-manager.io/cluster-issuer`                                          | Same — cert-manager annotations are not NGINX-specific                                                           |

Share your existing customizations with your FlowX representative during the upgrade window so they can be carried forward.

### Default proxy body size

Three services ship with a default `proxy-body-size: 50m` annotation to support larger uploads:

* `application-manager` — admin route (application manifests)
* `document-plugin` — admin and public routes (document uploads)
* `runtime-manager` — admin route (application-version manifests)

If you need a higher limit, coordinate the override with your FlowX representative.

### Ingress controller

Kubernetes Ingress resources work with any compliant controller (Traefik, HAProxy, Istio, F5 Container Ingress Services, cloud-provider controllers). Confirm the deployment's `ingressClassName` matches the controller actually running on your cluster with your FlowX representative.

***

## Troubleshooting

### CORS errors in the browser

The browser console shows `Access-Control-Allow-Origin` errors but the request reaches the backend successfully.

1. Confirm the origin is listed in `APPLICATION_CORS_ALLOWORIGIN` on the affected service (deployment guidelines table lists the variable per service).
2. Check the value is a comma-separated string of full origins, including the scheme (`https://`).
3. Restart the service after changing the env var — Spring reads it at startup.

### 413 Request Entity Too Large

A file upload or large request body fails with HTTP 413.

1. The default `proxy-body-size: 50m` applies to the three upload-heavy routes (`application-manager`, `document-plugin`, `runtime-manager` admin). Raise the value with your FlowX representative if you need higher.
2. If you front the FlowX cluster with an external reverse proxy (F5, corporate gateway, cloud LB), check the body size limit at that layer too.

### 404 / path routing issues

A request returns 404 even though the service is healthy.

1. Cross-check the external path against [Service route reference](#service-route-reference) — the path your client sends must match the table.
2. Confirm the deployment's `ingressClassName` (Ingress mode) or attached Gateway (HTTPRoute mode) matches the controller actually running in the cluster.

***

## Related resources

<CardGroup>
  <Card title="Migrating ingress from 5.1.x" icon="arrow-up-right-from-square" href="/5.9/migrating-from-5.1-lts/ingress-routing">
    NGINX controller change, CORS env var, and the upgrade-window action checklist.
  </Card>

  <Card title="v5.9.0 deployment guidelines" icon="file-lines" href="/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9">
    Component versions, Kafka topics, and the `APPLICATION_CORS_ALLOWORIGIN` row per service.
  </Card>

  <Card title="Gateway API documentation" icon="book" href="https://gateway-api.sigs.k8s.io/docs/introduction/">
    Upstream documentation for HTTPRoute, GatewayClass, and Gateway resources.
  </Card>

  <Card title="Setup guides" icon="server" href="./setup-guides-overview">
    Per-service configuration including each service's own routing and CORS section.
  </Card>
</CardGroup>


# Integration Designer setup
Source: https://docs.flowx.ai/5.9/setup-guides/integration-designer-setup

This guide explains how to configure the Integration Designer service using environment variables.

## Configuration

### Core service configuration

| Environment variable | Description               | Default value |
| -------------------- | ------------------------- | ------------- |
| `LOGGING_LEVEL_APP`  | Application logging level | `INFO`        |

### Service communication

| Environment variable               | Description                                                                 | Default value                             |
| ---------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------- |
| `FLOWX_CMS_BASEURL`                | Base URL for the CMS service                                                | `http://cms-core:80`                      |
| `FLOWX_NOSQLDBRUNNER_BASEURL`      | Base URL for the NoSQL DB Runner service                                    | `http://nosql-db-runner:80`               |
| `FLOWX_DOCUMENTPLUGIN_BASEURL`     | Base URL for the Document Plugin service                                    | `http://document-plugin:80`               |
| `FLOWX_AISERVICE_BASEURL`          | Base URL for the AI Platform service                                        | `http://ai-platform-connected-graph:9100` |
| `FLOWX_WEBHOOKGATEWAY_BASEURL`     | Base URL for the Webhook Gateway service                                    | `http://webhook-gateway:80`               |
| `FLOWX_WEBCRAWLER_BASEURL`         | Base URL for the web-crawler service (Web Page Extractor node)              | `http://web-crawler:80`                   |
| `FLOWX_ADMIN_BASEURL`              | Base URL for the Admin service                                              | `http://admin:80`                         |
| `FLOWX_EMAILGATEWAY_BASEURL`       | Base URL for the Email Gateway service                                      | `http://email-gateway:80`                 |
| `FLOWX_NOTIFICATIONPLUGIN_BASEURL` | Base URL for the Notification Plugin service                                | `http://notification-plugin:80`           |
| `FLOWX_DATAMODEL_BASEURL`          | Base URL for the Data Model service                                         | `http://admin:80`                         |
| `FLOWX_DOCPARSER_BASEURL`          | Base URL for the Document Parser service                                    | `http://doc-parser:80`                    |
| `FLOWX_SPEECHTOTEXT_BASEURL`       | Base URL for the Speech-to-Text service                                     | `http://speech-to-text:80`                |
| `FLOWX_FILEGATEWAY_BASEURL`        | Base URL for the File Gateway service, used by the File Storage data source | `http://file-gateway:80`                  |

| Environment variable               | Description                                                                                                                                   | Default value            |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `FLOWX_DATAPRIVACY_BASEURL`        | Base URL for the Data Privacy service used by the Personal Information Guard on AI workflow nodes (input/output PII detection and redaction). | `http://data-privacy:80` |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60`                     |

### Storage configuration

S3 storage for files in Integration Designer.

| Variable                                       | Default Value       | Description           |
| ---------------------------------------------- | ------------------- | --------------------- |
| `APPLICATION_FILESTORAGE_TYPE`                 | `s3`                | 🆕 Storage type       |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY`    | `NONE`              | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY`     | `delete`            | 🆕 Deletion strategy  |
| `APPLICATION_FILESTORAGE_S3_ENABLED`           | `true`              | 🆕 S3 enabled         |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`         | `http://minio:9000` | S3 server URL         |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false`             | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY`         | -                   | S3 access key         |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY`         | -                   | S3 secret key         |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`      | `workflows-bucket`  | 🆕 S3 bucket prefix   |

#### Redis

Integration Designer uses Redis for caching workflow execution data.

**Cache-specific configuration:**

| Variable                        | Description        | Default Value                            |
| ------------------------------- | ------------------ | ---------------------------------------- |
| `SPRING_CACHE_TYPE`             | Cache type         | `redis`                                  |
| `SPRING_CACHE_REDIS_KEYPREFIX`  | Cache key prefix   | `flowx:core:cache:integration-designer:` |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | Cache time to live | `5000000`                                |

**Redis connection:**

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

### WebClient configuration

Integration Designer interacts with various APIs, some of which return large responses. To handle such cases efficiently, the FlowX WebClient buffer size must be configured to accommodate larger payloads, especially when working with legacy APIs that do not support pagination.

| Environment variable                          | Description                                | Default value     |
| --------------------------------------------- | ------------------------------------------ | ----------------- |
| `FLOWX_WEBCLIENT_BUFFERSIZE`                  | Buffer size (in bytes) for FlowX WebClient | `52428800` (50MB) |
| `FLOWX_WEBCLIENT_BUFFERSIZEFORDOCUMENTPLUGIN` | Buffer size for Document Plugin calls      | `20971520` (20MB) |
| `FLOWX_WEBCLIENT_COMPRESSIONENABLED`          | Enable response compression                | `true`            |

### Workflow execution configuration

| Environment variable                 | Description                                    | Default value |
| ------------------------------------ | ---------------------------------------------- | ------------- |
| `FLOWX_WORKFLOW_MAXEXECUTEDNODES`    | Maximum number of nodes a workflow can execute | `1000`        |
| `FLOWX_WORKFLOW_MAXSUBWORKFLOWDEPTH` | Maximum nesting depth for subworkflows         | `100`         |
| `FLOWX_SCRIPTENGINE_ALLOWUNSAFEEVAL` | Allow unsafe eval in workflow scripts          | `false`       |

### AI service configuration

| Environment variable                       | Description                                                                                                 | Default value |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_AISERVICE_GENERALTIMEOUTSECONDS`    | General timeout for AI Platform service calls (seconds)                                                     | `30`          |
| `FLOWX_AISERVICE_NODERUNNERTIMEOUTSECONDS` | Timeout for AI node execution in workflows (seconds). Increase for Custom Agent nodes with many tool calls. | `600`         |

<Warning>
  `FLOWX_WORKFLOW_MAXEXECUTEDNODES` is a safety guardrail — workflows that exceed this limit are terminated. Increase only if your workflows legitimately require more node executions.
</Warning>

### Agent Builder configuration

| Environment variable      | Description                                        | Default value               |
| ------------------------- | -------------------------------------------------- | --------------------------- |
| `FLOWX_AGENTBUILDER_HOST` | Hostname of the AI Platform Agent Builder service  | `ai-platform-agent-builder` |
| `FLOWX_AGENTBUILDER_PORT` | gRPC port of the AI Platform Agent Builder service | `9100`                      |

### Process Engine configuration

| Environment variable          | Description                            | Default value              |
| ----------------------------- | -------------------------------------- | -------------------------- |
| `FLOWX_PROCESSENGINE_BASEURL` | Base URL of the Process Engine service | `http://process-engine:80` |

### MCP client configuration

Timeouts for MCP (Model Context Protocol) server connections used by MCP Server data sources.

| Environment variable                 | Description                                    | Default value                |
| ------------------------------------ | ---------------------------------------------- | ---------------------------- |
| `MCP_CLIENT_CONNECTTIMEOUT`          | TCP connect timeout for MCP server connections | `5s`                         |
| `MCP_CLIENT_REQUESTTIMEOUT`          | Request timeout for MCP server calls           | `30s`                        |
| `MCP_CLIENT_PREFLIGHTCONNECTTIMEOUT` | Connect timeout for preflight (health) checks  | `5s`                         |
| `MCP_CLIENT_PREFLIGHTREADTIMEOUT`    | Read timeout for preflight checks              | `5s`                         |
| `MCP_CLIENT_CLIENTNAME`              | Client name sent in MCP handshake              | `flowx-integration-designer` |

### Async AI callback configuration

Controls how timed-out AI node callbacks are reaped.

| Environment variable                   | Description                                               | Default value |
| -------------------------------------- | --------------------------------------------------------- | ------------- |
| `FLOWX_ASYNC_AI_CALLBACK_TTL`          | Time-to-live for pending AI callbacks before they expire  | `PT24H`       |
| `FLOWX_ASYNC_AI_REAPER_FIXED_DELAY_MS` | Interval (ms) between reaper sweeps for expired callbacks | `5000`        |
| `FLOWX_ASYNC_AI_REAPER_MAX_PER_TICK`   | Maximum expired callbacks reaped per sweep                | `200`         |

### Script engine configuration

Integration Designer uses a native script engine for executing JavaScript and Python scripts in workflow nodes. The native engine runs scripts in separate Node.js and Python worker processes.

| Environment variable                                                  | Description                                    | Default value    |
| --------------------------------------------------------------------- | ---------------------------------------------- | ---------------- |
| `APPLICATION_SCRIPTENGINE_PROVIDER`                                   | Script engine provider (`native` or `graalvm`) | `native`         |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE`                   | Number of Node.js worker processes             | `16`             |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS`         | Execution timeout per script (ms)              | `5000`           |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER`     | Max executions before a worker is recycled     | `10000`          |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES`        | Max input payload size (bytes)                 | `1048576` (1 MB) |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE`               | Number of Python worker processes              | `8`              |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`     | Execution timeout per script (ms)              | `10000`          |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a worker is recycled     | `10000`          |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES`    | Max input payload size (bytes)                 | `1048576` (1 MB) |

<Info>
  The `native` script engine is the default starting with 5.9.0. It replaces the previous GraalVM-based engine and runs scripts in isolated Node.js / Python subprocess pools. If you need to revert to GraalVM, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`.
</Info>

### Knowledge Base RAG configuration

| Environment variable | Description                                             | Default value                   |
| -------------------- | ------------------------------------------------------- | ------------------------------- |
| `FLOWX_KBRAG_HOST`   | Hostname of the AI Platform Knowledge Base RAG service  | `ai-platform-knowledgebase-rag` |
| `FLOWX_KBRAG_PORT`   | gRPC port of the AI Platform Knowledge Base RAG service | `9100`                          |

### Oracle SQL schema discovery

| Environment variable            | Description                                                                            | Default value |
| ------------------------------- | -------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for cached schema discovery responses (duration format, e.g. `24h`, `1h`) | `24h`         |

### Retry configuration

| Environment variable                                  | Description                                  | Default value     |
| ----------------------------------------------------- | -------------------------------------------- | ----------------- |
| `FLOWX_RETRY_THREADS`                                 | Worker threads for retry processing          | `20`              |
| `FLOWX_RETRY_PICKINGPAUSEMILLIS`                      | Pause between retry picking batches (ms)     | `500`             |
| `FLOWX_RETRY_COOLDOWNAFTERSECONDS`                    | Cooldown period after retry processing (sec) | `120`             |
| `FLOWX_RETRY_SCHEDULER_UNBLOCKRETRIES_CRONEXPRESSION` | Cron expression for unblocking retries       | `"*/2 * * * * ?"` |

### Database configuration

#### Advancing database

The [Advancing Controller](../docs/platform-deep-dive/core-components/advancing-controller) is a support service that optimizes advancing operations by ensuring efficient, balanced workload distribution—especially during scale-up and scale-down events. To enable Integration Designer to interact with the Advancing database, configure the following environment variables:

<Info>
  It can connect to the same database as the FlowX.AI Engine.
</Info>

| Environment variable                   | Description       | Default value                                 |
| -------------------------------------- | ----------------- | --------------------------------------------- |
| `ADVANCING_DATASOURCE_URL`             | Database JDBC URL | `jdbc:postgresql://postgresql:5432/advancing` |
| `ADVANCING_DATASOURCE_USERNAME`        | Database username | `flowx`                                       |
| `ADVANCING_DATASOURCE_PASSWORD`        | Database password | -                                             |
| `ADVANCING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class | `org.postgresql.Driver`                       |

#### Configuring the Advancing controller

| Environment variable                           | Description                                       | Default value     |
| ---------------------------------------------- | ------------------------------------------------- | ----------------- |
| `ADVANCING_PROCESSINGTHREADS`                  | Number of worker threads for advancing operations | `20`              |
| `ADVANCING_PICKINGPAUSEMILLIS`                 | Pause duration between picking batches (ms)       | `50`              |
| `ADVANCING_COOLDOWNAFTERSECONDS`               | Cooldown period after processing (seconds)        | `120`             |
| `ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION` | Cron expression for the heartbeat                 | `"*/2 * * * * ?"` |

| Environment variable                           | Description                                                                      | Default value     |
| ---------------------------------------------- | -------------------------------------------------------------------------------- | ----------------- |
| `ADVANCING_PICKINGTHREADS`                     | Number of worker threads for reading from database (picking operations)          | `1`               |
| `ADVANCING_PROCESSINGTHREADS`                  | Number of threads for parallel processing of advancing events                    | `20`              |
| `ADVANCING_PROCESSINGBUFFERSIZE`               | Maximum buffer size for processing queue. Controls how many events can be queued | `20`              |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`    | Block picking operations when no worker threads are available                    | `true`            |
| `ADVANCING_PICKINGPAUSEMILLIS`                 | Pause duration between picking batches (ms)                                      | `50`              |
| `ADVANCING_COOLDOWNAFTERSECONDS`               | Cooldown period after processing a batch (seconds)                               | `120`             |
| `ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION` | Cron expression for the heartbeat                                                | `"*/2 * * * * ?"` |

<Info>
  **How the new advancing controller works:**

  * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.

  * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space (even just 1 position), that amount of events will be read.

  * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
</Info>

<Info>
  The Advancing Controller supports multiple database systems including PostgreSQL and Oracle. Ensure you configure the appropriate JDBC URL and driver class for your chosen database system.
</Info>

### Workflow partitioning configuration

Workflow partitioning allows you to manage workflow instance data more efficiently by organizing data into time-based partitions. This is particularly useful for large-scale deployments where workflow instances accumulate over time.

| Environment variable                                   | Description                                          | Default value | Options                   |
| ------------------------------------------------------ | ---------------------------------------------------- | ------------- | ------------------------- |
| `FLOWX_DATA_PARTITIONING_ENABLED`                      | Turn on or off workflow instance partitioning        | `false`       | `true`, `false`           |
| `FLOWX_DATA_PARTITIONING_INTERVAL`                     | Time interval for creating partitions                | `MONTH`       | `DAY`, `WEEK`, `MONTH`    |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`            | Turn on or off automatic archiving of old partitions | `false`       | `true`, `false`           |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | Number of intervals to retain before archiving       | `3`           | Any positive integer      |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`     | cron expression for archiving schedule               | `0 0 1 * * ?` | Any valid cron expression |

<Info>
  **How workflow partitioning works:**

  * **Partitioning**: When turned on, workflow instances are stored in time-based partitions according to the specified interval.
  * **Partition interval**: Determines how frequently new partitions are created (`DAY`, `WEEK`, or `MONTH`).
  * **Archiving**: When turned on, automatically archives partitions older than the specified retention intervals. For example, with `MONTH` interval and `3` retention intervals, partitions older than 3 months will be archived.
  * **Archiving schedule**: The cron expression controls when the archiving process runs. The default `0 0 1 * * ?` runs daily at 1:00 AM.
</Info>

<Warning>
  Turn on partitioning and archiving only after careful planning and testing. Once turned on, ensure that your database has sufficient storage for partition management operations. It's recommended to start with archiving turned off and turn it on only after verifying that partitioning works correctly for your use case.
</Warning>

#### MongoDB

Integration Designer requires two MongoDB databases for managing integration-specific data and runtime data:

* **Integration Designer Database** (`integration-designer`): Stores data specific to Integration Designer, such as integration configurations, metadata, and other operational data.
* **Shared Runtime Database** (`app-runtime`): Shared across multiple services, this database manages runtime data essential for integration and data flow execution.

| Environment variable                   | Description                            | Default value                                                     |
| -------------------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI`              | Integration Designer MongoDB URI       | `mongodb://mongodb-0.mongodb-headless:27017/integration-designer` |
| `SPRING_DATA_MONGODB_USERNAME`         | MongoDB username                       | `integration-designer`                                            |
| `SPRING_DATA_MONGODB_PASSWORD`         | MongoDB password                       |                                                                   |
| `SPRING_DATA_MONGODB_STORAGE`          | Storage type (Azure environments only) | `mongodb` (or `cosmosdb`)                                         |
| `SPRING_DATA_MONGODB_RUNTIME_URI`      | Runtime MongoDB URI                    | `mongodb://mongodb-0.mongodb-headless:27017/app-runtime`          |
| `SPRING_DATA_MONGODB_RUNTIME_USERNAME` | Runtime MongoDB username               | `app-runtime`                                                     |
| `SPRING_DATA_MONGODB_RUNTIME_PASSWORD` | Runtime MongoDB password               |                                                                   |

<Info>
  Integration Designer requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.
</Info>

### Configuration parameters

There are two types of Config Params that can be read from the environment: **variables** and **secrets**. There is one provider for variables and secrets extracted from the environment variables, and two providers for the ones extracted from Kubernetes. By default, the variables and secrets are extracted from environment variables (`env` provider).

#### Configuration parameters from environment variables (default)

The `env` provider used for variables and secrets extracts them from environment variables. For security reasons, the `env` provider uses an allow list regex which defaults to `FLOWX_CONFIGPARAM_.*`. This means only environment variables that match this naming pattern can be read at runtime into configuration params (either as variables or secrets). Feel free to edit it to match the environment variables that you use in your deployment.

| Environment variable                        | Description                                                     | Default value          |
| ------------------------------------------- | --------------------------------------------------------------- | ---------------------- |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER`          | Provider type for variables                                     | `env`                  |
| `FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX`    | Regular expression to match allowed env variables for variables | `FLOWX_CONFIGPARAM_.*` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER`       | Provider type for secrets                                       | `env`                  |
| `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX` | Regular expression to match allowed env variables for secrets   | `FLOWX_CONFIGPARAM_.*` |

#### Configuration parameters from Kubernetes Secrets and ConfigMaps

Use the following configuration to read Config Params from Kubernetes Secrets and ConfigMaps:

| Environment variable                  | Description                 | Values           |
| ------------------------------------- | --------------------------- | ---------------- |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER`    | Provider type for variables | `k8s-configmaps` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | Provider type for secrets   | `k8s-secrets`    |

These providers can be configured as follows:

| Environment variable                                          | Description                                | Values               |
| ------------------------------------------------------------- | ------------------------------------------ | -------------------- |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_0` | Name of the ConfigMap to use for variables | `flowx-configparams` |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_0`       | Name of the Secret to use for secrets      | `flowx-configparams` |

<Info>
  You can configure multiple secrets and ConfigMaps by incrementing the index number (e.g., `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_1`, `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_1`). In dev environments, the typical ConfigMap/Secret name is `flowx-rt`. Values are overridden based on the order in which the maps are defined.

  The default provider is `env`, but there is a built-in allowlist with the regex pattern `FLOWX_CONFIGPARAM_.*`. This means only configuration parameters that match this naming pattern can be read at runtime, whether they are environment variables or secret variables.
</Info>

### Kafka configuration

#### Kafka connection and security variables

| Environment variable          | Description                                                         | Default value                   |
| ----------------------------- | ------------------------------------------------------------------- | ------------------------------- |
| `KAFKA_BOOTSTRAP_SERVERS`     | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092`                |
| `KAFKA_SECURITY_PROTOCOL`     | Security protocol (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`)      | `PLAINTEXT` or `SASL_PLAINTEXT` |
| `FLOWX_WORKFLOW_CREATETOPICS` | Auto-create topics                                                  | `false` (default)               |

#### Message size configuration

| Environment variable      | Description          | Default value     |
| ------------------------- | -------------------- | ----------------- |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size | `52428800` (50MB) |

This setting affects:

* Producer message max bytes
* Producer max request size

#### Consumer configuration

| Environment variable                                 | Description                                      | Default value                                          |
| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------ |
| `KAFKA_CONSUMER_GROUPID_STARTWORKFLOWS`              | Start workflows consumer group                   | `start-workflows-group`                                |
| `KAFKA_CONSUMER_GROUPID_RESELEMUSAGEVALIDATION`      | Resource usage validation consumer group         | `integration-designer-res-elem-usage-validation-group` |
| `KAFKA_CONSUMER_GROUPID_SYSTEMSYNC`                  | System sync consumer group                       | `system-sync-group`                                    |
| `KAFKA_CONSUMER_GROUPID_WORKFLOWSYNC`                | Workflow sync consumer group                     | `workflow-sync-group`                                  |
| `KAFKA_CONSUMER_GROUPID_CORRECTIONAFTERAPPOPERATION` | Correction after app operation consumer group    | `correction-after-app-operation-group`                 |
| `KAFKA_CONSUMER_GROUPID_STOREENTRYINDEXERRESPONSE`   | KB store entry indexer response consumer group   | `store-entry-indexer-response-group`                   |
| `KAFKA_CONSUMER_THREADS_STARTWORKFLOWS`              | Start workflows consumer threads                 | `3`                                                    |
| `KAFKA_CONSUMER_THREADS_RESELEMUSAGEVALIDATION`      | Resource usage validation consumer threads       | `3`                                                    |
| `KAFKA_CONSUMER_THREADS_SYSTEMSYNC`                  | System sync consumer threads                     | `3`                                                    |
| `KAFKA_CONSUMER_THREADS_WORKFLOWSYNC`                | Workflow sync consumer threads                   | `3`                                                    |
| `KAFKA_CONSUMER_THREADS_CORRECTIONAFTERAPPOPERATION` | Correction after app operation consumer threads  | `3`                                                    |
| `KAFKA_CONSUMER_THREADS_STOREENTRYINDEXERRESPONSE`   | KB store entry indexer response consumer threads | `3`                                                    |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`                   | Retry interval after authorization errors        | `10` (seconds)                                         |

#### Topic naming convention and pattern creation

The Integration Designer uses a structured topic naming convention that follows a standardized pattern, ensuring consistency across environments and making topics easily identifiable.

##### Topic naming components

| Environment variable                           | Description                 | Default value          |
| ---------------------------------------------- | --------------------------- | ---------------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`                   | Base package for topics     | `ai.flowx.`            |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT`               | Environment identifier      | ` `                    |
| `KAFKA_TOPIC_NAMING_VERSION`                   | Topic version               | `.v1`                  |
| `KAFKA_TOPIC_NAMING_SEPARATOR`                 | Topic name separator        | `.`                    |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`                | Alternative separator       | `-`                    |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN`      | Engine receive pattern      | `engine.receive.`      |
| `KAFKA_TOPIC_NAMING_INTEGRATIONRECEIVEPATTERN` | Integration receive pattern | `integration.receive.` |

Topics are constructed using the following pattern:

```
{prefix} + service + {separator/dot} + action + {separator/dot} + detail + {suffix}
```

For example, a typical topic might look like:

```
ai.flowx.eventsgateway.receive.workflowinstances.v1
```

Where:

* `ai.flowx.` is the prefix (package + environment)
* `eventsgateway` is the service
* `receive` is the action
* `workflowinstances` is the detail
* `.v1` is the suffix (version)

#### Kafka topic configuration

##### Core topics

| Environment variable    | Description                  | Default Pattern                       |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

##### Events gateway topics

| Environment variable                    | Description                                | Default Pattern                                       |
| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Topic for workflow instances communication | `ai.flowx.eventsgateway.receive.workflowinstances.v1` |

##### UI flow session variable updates

When a workflow triggered by a UI Flow finishes, the integration-designer sends the result to the process-engine so the session variables are updated automatically.

| Environment variable            | Description                                                                               | Default Pattern                           |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending workflow results to process-engine for UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` |

##### Knowledge Base store entry lifecycle topics

These topics handle communication between Integration Designer and the AI Platform for Knowledge Base store entry indexing operations.

| Environment variable                     | Description                                                                    | Default Pattern                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `KAFKA_TOPIC_KB_STOREENTRYLIFECYCLE_IN`  | Topic for receiving KB store entry index responses from AI Platform (consumed) | `ai.flowx.ai-platform.knowledgebase.store-entry.index-response.v1` |
| `KAFKA_TOPIC_KB_STOREENTRYLIFECYCLE_OUT` | Topic for sending KB store entry index requests to AI Platform (produced)      | `ai.flowx.ai-platform.knowledgebase.store-entry.index-request.v1`  |

##### AI Platform job topics

Integration Designer dispatches document parsing, speech-to-text, and evaluation jobs to the AI Platform over Kafka. Each job family has a request topic (produced), a response topic (consumed), and a dead-letter topic (consumed).

| Environment variable                          | Description                                        | Default Pattern                                       |
| --------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------- |
| `KAFKA_TOPIC_AI_DOCPARSER_JOB_REQUEST_OUT`    | Document Parser job requests (produced)            | `ai.flowx.ai-platform.doc-parser.job.request.v1`      |
| `KAFKA_TOPIC_AI_DOCPARSER_JOB_RESPONSE_IN`    | Document Parser job responses (consumed)           | `ai.flowx.ai-platform.doc-parser.job.response.v1`     |
| `KAFKA_TOPIC_AI_DOCPARSER_JOB_DLQ_IN`         | Document Parser job dead-letter queue (consumed)   | `ai.flowx.ai-platform.doc-parser.job.dlq.v1`          |
| `KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_REQUEST_OUT` | Speech-to-Text job requests (produced)             | `ai.flowx.ai-platform.speech-to-text.job.request.v1`  |
| `KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_RESPONSE_IN` | Speech-to-Text job responses (consumed)            | `ai.flowx.ai-platform.speech-to-text.job.response.v1` |
| `KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_DLQ_IN`      | Speech-to-Text job dead-letter queue (consumed)    | `ai.flowx.ai-platform.speech-to-text.job.dlq.v1`      |
| `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`   | Evaluations judge job requests (produced)          | `ai.flowx.ai-platform.evals-judge.job.request.v1`     |
| `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_RESPONSE_IN`   | Evaluations judge job responses (consumed)         | `ai.flowx.ai-platform.evals-judge.job.response.v1`    |
| `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_DLQ_IN`        | Evaluations judge job dead-letter queue (consumed) | `ai.flowx.ai-platform.evals-judge.job.dlq.v1`         |

##### Engine and Integration communication topics

| Environment variable             | Description                           | Default Pattern                  |
| -------------------------------- | ------------------------------------- | -------------------------------- |
| `KAFKA_TOPIC_ENGINEPATTERN`      | Pattern for Engine communication      | `ai.flowx.engine.receive.`       |
| `KAFKA_TOPIC_INTEGRATIONPATTERN` | Pattern for Integration communication | `ai.flowx.integration.receive.*` |

##### Application topics

**Outbound topics:**

| Environment variable                                              | Description                             | Default Pattern                                                           |
| ----------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
| `KAFKA_TOPIC_APPLICATION_OUT_SYNCRESPONSE`                        | Sync response messages                  | `ai.flowx.application-version.sync.out.v1`                                |
| `KAFKA_TOPIC_APPLICATION_OUT_CORRECTIONAFTERAPPOPERATIONRESPONSE` | Correction after app operation response | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA`                                   | Build runtime data                      | `ai.flowx.build.runtime-data.v1`                                          |
| `KAFKA_TOPIC_LICENSE_OUT_USAGE`                                   | License usage tracking                  | `ai.flowx.license.usage.v1`                                               |

<Info>
  The `sync.out.v1` and `correction-after-app-operation.response.v1` topics exist since 5.1.x (produced by admin). Starting with 5.5.0, integration-designer also produces to these shared response topics for system and workflow sync/correction operations.
</Info>

**Inbound topics:**

| Environment variable                                              | Description                             | Default Pattern                                                                           |
| ----------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- |
| `KAFKA_TOPIC_APPLICATION_IN_RESELEMUSAGEVALIDATION`               | Resource usage validation requests      | `ai.flowx.application-version.resources-usages.sub-res-validation.request-integration.v1` |
| `KAFKA_TOPIC_APPLICATION_IN_SYSTEMSYNCREQUEST`                    | System sync requests                    | `ai.flowx.application-version.sync.system.in.v1`                                          |
| `KAFKA_TOPIC_APPLICATION_IN_WORKFLOWSYNCREQUEST`                  | Workflow sync requests                  | `ai.flowx.application-version.sync.workflow.in.v1`                                        |
| `KAFKA_TOPIC_APPLICATION_IN_CORRECTIONAFTERAPPOPERATION_SYSTEM`   | System correction after app operation   | `ai.flowx.application-version.correction-after-app-operation.system.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_IN_CORRECTIONAFTERAPPOPERATION_WORKFLOW` | Workflow correction after app operation | `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1`         |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH`                             | Resource usage refresh commands         | `ai.flowx.application-version.resources-usages.refresh.v1`                                |

#### OAuth authentication variables (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Inter-Service topic coordination

When configuring Kafka topics in the FlowX ecosystem, ensure proper coordination between services:

1. **Topic name matching**: Output topics from one service must match the expected input topics of another service.

2. **Pattern consistency**: The pattern values must be consistent across services:

   * Process Engine listens to topics matching: `ai.flowx.engine.receive.*`
   * Integration Designer listens to topics matching: `ai.flowx.integration.receive.*`

3. **Communication flow**:
   * Other services write to topics matching the Engine's pattern → Process Engine listens
   * Process Engine writes to topics matching the Integration Designer's pattern → Integration Designer listens

<Info>
  The exact pattern value isn't critical, but it must be identical across all connected services. Some deployments require manually creating Kafka topics in advance rather than dynamically. In these cases, all topic names must be explicitly defined and coordinated.
</Info>

### Kafka topics best practices

#### Large message handling for workflow instances topic

The workflow instances topic requires special configuration to handle large messages. By default, Kafka has message size limitations that may prevent Integration Designer from processing large workflow payloads.

**Recommended `max.message.bytes` value**: `10485760` (10 MB)

#### Method: update using AKHQ (recommended)

1. **Access AKHQ**
   * Open the AKHQ web interface
   * Log in if authentication is required

2. **Navigate to Topic**
   * Go to the "Topics" section
   * Find the topic: `ai.flowx.eventsgateway.receive.workflowinstances.v1`

3. **Edit Configuration**
   * Click on the topic name
   * Go to the "Configuration" tab
   * Locate or add `max.message.bytes`
   * Set the value to `10485760`
   * Save changes

### CAS lib configuration

CAS lib is used to communicate with the authorization-service through SpiceDB.

| Environment variable  | Description      | Default value |
| --------------------- | ---------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | Spicedb host     | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | Spicedb port     | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | Spicedb db token | `REPLACEME`   |

### Configuring authentication and access roles

Integration Designer validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment variable                                                        | Description                                                                                                                                           | Default value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-integration-designer-sa`                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

For detailed instructions on configuring user roles and access rights, refer to:

<Card title="Access Management" href="./access-management/access-management-overview" icon="lock" />

For configuring a service account, refer to:

<Card title="Integration Designer service account" href="./access-management/configuring-an-iam-solution#integration-designer-service-account" icon="lock" />

### Configuring logging

To control the log levels for Integration Designer, set the following environment variables:

| Environment variable | Description                  | Default value |
| -------------------- | ---------------------------- | ------------- |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot logs level  | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-level logs level | `INFO`        |

### Configuring admin ingress

The Integration Designer service uses the standard FlowX.AI ingress pattern. For complete setup instructions including the full ingress template, CORS configuration, and troubleshooting, see the [Ingress Configuration Guide](./ingress-configuration).

**Service-specific values for Integration Designer:**

* **Ingress name:** `integration-designer-admin`
* **Service path:** `/integration(/|$)(.*)`
* **Service name:** `integration-designer`
* **Rewrite target:** `/$2`
* **Fx-Workspace-Id:** Required

<Card title="Complete Ingress Configuration" href="./ingress-configuration" icon="network-wired">
  View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.
</Card>

### Monitoring and maintenance

To monitor the performance and health of the Integration Designer, use tools like Prometheus or Grafana. Configure Prometheus metrics with:

| Environment variable                           | Description                      | Default value |
| ---------------------------------------------- | -------------------------------- | ------------- |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enable Prometheus metrics export | `false`       |

### RBAC configuration

Integration Designer requires specific RBAC (Role-Based Access Control) permissions to access Kubernetes ConfigMaps and Secrets, which store necessary configurations and credentials. Set up these permissions by enabling RBAC and defining the required rules:

```yaml theme={"system"}
rbac:
  create: true
  rules:
    - apiGroups:
        - ""
      resources:
        - secrets
        - configmaps
        - pods
      verbs:
        - get
        - list
        - watch
```

This configuration grants read access (`get`, `list`, `watch`) to ConfigMaps, Secrets, and Pods, which is essential for retrieving application settings and credentials required by Integration Designer.

***

## Ingress and CORS

The Integration Designer service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path  | Backend receives |
| ---------- | -------------- | ---------------- |
| admin      | `/integration` | `/`              |

The path is set through `services.integration-designer.ingress.admin.path` (or `services.integration-designer.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                                | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Integration Designer. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Integration Designer fails to start">
    **Symptoms:** Service crashes on startup or fails health checks.

    **Solutions:**

    1. Verify MongoDB connection URIs for both the `integration-designer` and `app-runtime` databases
    2. Check that Kafka broker addresses are reachable and the security protocol is correct
    3. Ensure the Keycloak service account is properly configured and the client secret is valid
    4. Review logs at `LOGGING_LEVEL_APP=DEBUG` for detailed startup error messages
  </Accordion>

  <Accordion title="REST connector calls failing">
    **Symptoms:** Workflow executions fail at REST connector nodes with timeout or connection errors.

    **Solutions:**

    1. Verify network connectivity between the Integration Designer pod and the target system
    2. Check SSL/TLS certificates if the target system uses HTTPS
    3. Review timeout settings and increase `FLOWX_WEBCLIENT_BUFFERSIZE` if responses are large
    4. Ensure firewall rules and network policies allow outbound traffic to the target host and port
  </Accordion>

  <Accordion title="Workflow execution errors">
    **Symptoms:** Workflows start but fail during execution with Kafka or data mapping errors.

    **Solutions:**

    1. Verify that all required Kafka topics exist and are correctly named across services
    2. Check that input/output parameter mappings match the expected data model
    3. Ensure the `KAFKA_TOPIC_ENGINEPATTERN` and `KAFKA_TOPIC_INTEGRATIONPATTERN` values are consistent with the Process Engine configuration
    4. Review the events gateway topic (`KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE`) for message delivery issues
  </Accordion>

  <Accordion title="Data sources not connecting">
    **Symptoms:** Data sources configured in Integration Designer show connection errors or timeouts.

    **Solutions:**

    1. Verify that the credentials for the target data source are correct and not expired
    2. Check network access between the Integration Designer pod and the data source endpoint
    3. Ensure firewall rules allow traffic on the required ports
    4. For S3-compatible storage issues, verify `APPLICATION_FILESTORAGE_S3_SERVERURL` and access key configuration
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Integration Designer" icon="pencil" href="../docs/platform-deep-dive/integrations/integration-designer">
    Learn about the Integration Designer and how to build integration workflows
  </Card>

  <Card title="Building a Connector" icon="plug" href="../docs/platform-deep-dive/integrations/building-a-connector">
    Step-by-step guide for creating connectors in Integration Designer
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>

  <Card title="Events Gateway Setup" icon="bolt" href="./events-gateway-setup">
    Configure the Events Gateway for inter-service communication
  </Card>
</CardGroup>


# Kafka Authentication profile
Source: https://docs.flowx.ai/5.9/setup-guides/kafka-authentication-config

Enable secure Kafka communication across Java microservices using Spring configuration profiles

The FlowX.AI platform supports enabling **Kafka authentication** across all Java microservices using a dedicated **Spring configuration profile**. This feature simplifies the activation of secure Kafka communication by centralizing the configuration in one place.

<Info>
  Currently, **kafka-auth is the only supported profile** provided by the platform for Kafka authentication.
</Info>

## Understanding SPRING\_PROFILES\_ACTIVE

`SPRING_PROFILES_ACTIVE` is an environment variable used by Spring Boot to determine which configuration profiles should be active at runtime.

### Key characteristics

* **Multiple profiles**: Can contain one or more profile names, separated by commas
  * Example: `SPRING_PROFILES_ACTIVE=dev,kafka-auth`
* **Environment-specific behavior**: Profiles allow different sets of configuration to be loaded depending on the environment or required feature set
* **Special kafka-auth profile**: Activates Kafka authentication across services

<Warning>
  If `SPRING_PROFILES_ACTIVE` is not set, the application runs with the **default profile**, which does **not** include Kafka authentication.
</Warning>

## Configuration details

When the `kafka-auth` profile is enabled, the following **Spring Kafka properties** are automatically applied:

```yaml theme={"system"}
spring.config.activate.on-profile: kafka-auth

spring:
  kafka:
    security.protocol: "SASL_PLAINTEXT"
    properties:
      sasl:
        mechanism: "OAUTHBEARER"
        jaas.config: >
          org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required
          oauth.client.id="${KAFKA_OAUTH_CLIENT_ID:kafka}"
          oauth.client.secret="${KAFKA_OAUTH_CLIENT_SECRET:kafka-secret}"
          oauth.token.endpoint.uri="${KAFKA_OAUTH_TOKEN_ENDPOINT_URI:kafka.auth.localhost}" ;
        login.callback.handler.class: io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler
```

### Configuration properties explained

| Property                                                    | Purpose                                                    | Value                                                               |
| ----------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| `spring.kafka.security.protocol`                            | Defines Kafka communication protocol                       | `SASL_PLAINTEXT`                                                    |
| `spring.kafka.properties.sasl.mechanism`                    | Authentication mechanism used for SASL                     | `OAUTHBEARER`                                                       |
| `spring.kafka.properties.sasl.jaas.config`                  | JAAS login configuration referencing environment variables | See configuration                                                   |
| `spring.kafka.properties.sasl.login.callback.handler.class` | Callback handler for OAuth authentication                  | `io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler` |

## Required environment variables

The Kafka authentication profile uses environment variables to configure OAuth parameters dynamically. These variables should be set in the runtime environment for each microservice.

| Environment Variable             | Default Value          | Description                                                    |
| -------------------------------- | ---------------------- | -------------------------------------------------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | `kafka`                | OAuth client ID used to authenticate with the token endpoint   |
| `KAFKA_OAUTH_CLIENT_SECRET`      | `kafka-secret`         | Secret associated with the OAuth client ID                     |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | `kafka.auth.localhost` | OAuth token endpoint URI from which access tokens are obtained |

<Warning>
  These variables should be set in the runtime environment. If they are not provided, the defaults listed above will be used.
</Warning>

## Benefits

Enabling the Kafka authentication profile provides several advantages:

* **Centralized enablement**: Activates OAuth-based Kafka authentication consistently across services.
* **Configurable via environment variables**: No hardcoding of sensitive data in app configuration.
* **Simple activation**: Controlled entirely by the `SPRING_PROFILES_ACTIVE` variable.

## Notes and limitations

* Only the kafka-auth profile is currently supported for Kafka authentication.
* The profile enforces **SASL/OAUTHBEARER with plaintext transport**. Secure networking (for example, VPN, mTLS) should be ensured where required.


# Redis configuration
Source: https://docs.flowx.ai/5.9/setup-guides/redis-configuration

Configure Redis deployment modes for FlowX platform services

## Overview

FlowX platform services use Redis for caching and real-time data management. Redis can be deployed in three different modes depending on your availability and scalability requirements.

All FlowX Java microservices support the same Redis configuration properties based on Spring Boot's Redis data configuration.

## Supported deployment modes

FlowX supports three Redis deployment modes:

* **Standalone**: Single Redis instance (suitable for development and low-traffic environments)
* **Sentinel**: High availability with automatic failover (recommended for production)
* **Cluster**: Horizontal scaling with data sharding (for high-throughput applications)

<Warning>
  Master-Replica mode is not supported. Use Sentinel mode for high availability with automatic failover, or Cluster mode for horizontal scaling.
</Warning>

## Standalone mode

The default configuration for single Redis instance deployments.

### Configuration parameters

| Environment Variable            | Description                       | Example Value                      | Required                     |
| ------------------------------- | --------------------------------- | ---------------------------------- | ---------------------------- |
| `SPRING_DATA_REDIS_HOST`        | Hostname of the Redis server      | `localhost` or `redis.example.com` | Yes                          |
| `SPRING_DATA_REDIS_PORT`        | Port number for Redis server      | `6379` (default)                   | Yes                          |
| `SPRING_DATA_REDIS_PASSWORD`    | Password for Redis authentication | `yourpassword`                     | If authentication is enabled |
| `SPRING_DATA_REDIS_SSL_ENABLED` | Enable SSL/TLS connection         | `true` or `false`                  | No                           |

### Example configuration

```yaml theme={"system"}
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: yourpassword
      ssl:
        enabled: false
```

## Sentinel mode

For high-availability Redis with automatic failover. Sentinel provides monitoring, notification, and automatic failover capabilities.

### Configuration parameters

| Environment Variable                  | Description                                               | Example Value                         | Required                              |
| ------------------------------------- | --------------------------------------------------------- | ------------------------------------- | ------------------------------------- |
| `SPRING_DATA_REDIS_SENTINEL_MASTER`   | Name of the Redis master instance                         | `mymaster`                            | Yes                                   |
| `SPRING_DATA_REDIS_SENTINEL_NODES`    | Comma-separated list of Sentinel nodes (host:port format) | `host1:26379,host2:26379,host3:26379` | Yes                                   |
| `SPRING_DATA_REDIS_SENTINEL_PASSWORD` | Password for Sentinel authentication                      | `sentinelpassword`                    | If Sentinel authentication is enabled |
| `SPRING_DATA_REDIS_PASSWORD`          | Password for Redis data node authentication               | `yourpassword`                        | If Redis authentication is enabled    |

### Example configuration

```yaml theme={"system"}
spring:
  data:
    redis:
      sentinel:
        master: mymaster
        nodes: sentinel1:26379,sentinel2:26379,sentinel3:26379
        password: sentinelpassword
      password: yourpassword
```

### Important notes

<Info>
  * The `SPRING_DATA_REDIS_SENTINEL_NODES` must include all Sentinel instances for redundancy
  * Sentinel typically runs on port `26379` (different from Redis data port `6379`)
  * The master name (`SPRING_DATA_REDIS_SENTINEL_MASTER`) must match the master configured in your Sentinel setup
  * Both Sentinel password and Redis password can be configured independently
</Info>

## Cluster mode

For Redis cluster deployments with data sharding across multiple nodes, providing horizontal scalability.

### Configuration parameters

| Environment Variable              | Description                                              | Example Value                      | Required                     |
| --------------------------------- | -------------------------------------------------------- | ---------------------------------- | ---------------------------- |
| `SPRING_DATA_REDIS_CLUSTER_NODES` | Comma-separated list of cluster nodes (host:port format) | `host1:6379,host2:6379,host3:6379` | Yes                          |
| `SPRING_DATA_REDIS_PASSWORD`      | Password for Redis cluster authentication                | `yourpassword`                     | If authentication is enabled |

### Example configuration

```yaml theme={"system"}
spring:
  data:
    redis:
      cluster:
        nodes: node1:6379,node2:6379,node3:6379
      password: yourpassword
```

### Important notes

<Info>
  * You only need to specify a subset of cluster nodes; the Redis client will discover all nodes automatically
  * At least 3 master nodes are recommended for a production Redis cluster
  * Data is automatically sharded across cluster nodes
</Info>

## Choosing the right deployment mode

Use this guide to select the appropriate Redis deployment mode:

<Tabs>
  <Tab title="Development & Testing">
    **Standalone mode** is suitable for:

    * Development environments
    * Testing and staging environments
    * Low-traffic applications
    * Single-server deployments

    **Considerations:**

    * No automatic failover
    * Single point of failure
    * Simplest to set up and maintain
  </Tab>

  <Tab title="Production - High Availability">
    **Sentinel mode** is recommended for:

    * Production environments requiring high availability
    * Applications that need automatic failover
    * Deployments where downtime is not acceptable
    * Single-master write scenarios

    **Considerations:**

    * Automatic failover to replica nodes
    * Monitoring and notifications
    * More complex setup than standalone
    * No data sharding (vertical scaling)
  </Tab>

  <Tab title="Production - High Throughput">
    **Cluster mode** is ideal for:

    * High-throughput applications
    * Large datasets requiring data sharding
    * Horizontal scaling requirements
    * Multi-master write scenarios

    **Considerations:**

    * Data automatically distributed across nodes
    * Horizontal scalability
    * Most complex to set up and maintain
    * Different behavior than single-instance Redis (some commands not supported)
  </Tab>
</Tabs>

## SSL/TLS configuration

For secure Redis connections, you can enable SSL/TLS:

| Environment Variable            | Description                          | Example Value |
| ------------------------------- | ------------------------------------ | ------------- |
| `SPRING_DATA_REDIS_SSL_ENABLED` | Enable SSL/TLS for Redis connections | `true`        |

```yaml theme={"system"}
spring:
  data:
    redis:
      ssl:
        enabled: true
```

<Info>
  SSL/TLS configuration is supported in all deployment modes (Standalone, Sentinel, and Cluster).
</Info>

## Additional configuration options

### Connection timeout

| Environment Variable        | Description                        | Default Value |
| --------------------------- | ---------------------------------- | ------------- |
| `SPRING_DATA_REDIS_TIMEOUT` | Connection timeout in milliseconds | `2000`        |

### TTL (Time To Live)

Some services support custom TTL configuration for cached data:

| Environment Variable | Description                                     | Default Value    |
| -------------------- | ----------------------------------------------- | ---------------- |
| `REDIS_TTL`          | Time to live for cached entries in milliseconds | Service-specific |

<Info>
  Check individual service setup guides for service-specific Redis configuration options.
</Info>

## Applying configuration

<Steps>
  <Step title="Choose your deployment mode">
    Select the appropriate Redis deployment mode based on your requirements (Standalone, Sentinel, or Cluster).
  </Step>

  <Step title="Set environment variables">
    Configure the required environment variables for your chosen deployment mode in your deployment configuration (Kubernetes ConfigMap, Docker Compose, etc.).
  </Step>

  <Step title="Verify Redis connectivity">
    Ensure your FlowX services can reach the Redis instance(s) on the network level.
  </Step>

  <Step title="Test the configuration">
    Deploy your services and verify Redis connectivity through service logs and health checks.
  </Step>
</Steps>

## Services using Redis

The following FlowX services use Redis and support these configuration options:

* Events Gateway
* Authorization System
* FlowX Engine
* Notification Plugin
* Document Plugin
* OCR Plugin
* Task Management Plugin

<Info>
  For service-specific Redis configuration details, refer to the individual setup guides in the [Setup Guides section](/5.9/setup-guides/setup-guides-overview).
</Info>

## Troubleshooting

### Connection issues

If services cannot connect to Redis:

1. **Verify network connectivity**: Ensure the service can reach Redis hosts on the configured ports
2. **Check authentication**: Verify the password is correct
3. **Review firewall rules**: Ensure no firewall is blocking Redis ports
4. **Validate configuration**: Double-check environment variable names and values

### Sentinel mode issues

If Sentinel failover is not working:

1. **Verify master name**: Ensure `SPRING_DATA_REDIS_SENTINEL_MASTER` matches your Sentinel configuration
2. **Check all Sentinel nodes**: All Sentinel instances should be reachable
3. **Review Sentinel logs**: Check Sentinel logs for failover events
4. **Validate Sentinel password**: If using Sentinel authentication, ensure `SPRING_DATA_REDIS_SENTINEL_PASSWORD` is correct

### Cluster mode issues

If cluster operations fail:

1. **Verify cluster health**: Check Redis cluster status with `CLUSTER INFO`
2. **Ensure minimum nodes**: At least 3 master nodes should be running
3. **Check node discovery**: Ensure the service can discover all cluster nodes
4. **Review unsupported commands**: Some Redis commands are not supported in cluster mode

## Related documentation

<CardGroup>
  <Card title="Kafka Authentication" icon="lock" href="/5.9/setup-guides/kafka-authentication-config">
    Configure secure Kafka communication
  </Card>

  <Card title="Events Gateway Setup" icon="tower-broadcast" href="/5.9/setup-guides/events-gateway-setup">
    Complete Events Gateway configuration
  </Card>

  <Card title="Setup Guides Overview" icon="book" href="/5.9/setup-guides/setup-guides-overview">
    View all setup guides
  </Card>
</CardGroup>


# Runtime manager setup
Source: https://docs.flowx.ai/5.9/setup-guides/runtime-manager

This guide provides a step-by-step process for setting up and configuring the Runtime Manager module, including database, Kafka, and OAuth2 authentication settings to manage runtime and build configurations.

<Info>
  The [**Application Manager**](./application-manager) and **Runtime Manager** share the same container image and Helm chart. Refer to the **Deployment Guidelines** in the release notes to ensure compatibility and verify the correct version.
</Info>

## Infrastructure prerequisites

The Runtime Manager service requires the following components to be set up before it can be started:

* **PostgreSQL**
* **MongoDB**
* **Redis**
* **Kafka**
* **OAuth2 Authentication**

## Dependencies

* [**Database configuration**](#database-configuration)
* [**Kafka configuration**](#configuring-kafka)
* [**Authentication & access roles**](#configuring-authentication-and-access-roles)
* [**Logging**](./setup-guides-overview#logging)

## Change the application name

| Environment Variable      | Description                                               | Example Value     |
| ------------------------- | --------------------------------------------------------- | ----------------- |
| `SPRING_APPLICATION_NAME` | Service identifier used for service discovery and logging | `runtime-manager` |

<Warning>
  Default Value: `application-manager -> must be changed to `runtime-manager
</Warning>

## Core service configuration

| Environment Variable         | Description                                                                                                                                                                                                                                                                          | Example Value        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
| `FLOWX_ENVIRONMENT_NAME`     | Environment identifier (dev, staging, prod, etc.). *Deprecated in 5.7.0*: kept for backward compatibility; the value is no longer surfaced in the Designer's Configure Environment Info page (removed) and is replaced by the environment name set during organization provisioning. | `pr`                 |
| `LOGGING_CONFIG_FILE`        | Path to logging configuration file                                                                                                                                                                                                                                                   | `logback-spring.xml` |
| `MULTIPART_MAX_FILE_SIZE`    | Maximum file size for uploads                                                                                                                                                                                                                                                        | `25MB`               |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum total request size                                                                                                                                                                                                                                                           | `25MB`               |

## Database configuration

The Runtime Manager uses the same PostgreSQL (to store application data) and MongoDB (to manage runtime data) as [**application-manager**](application-manager). Configure these database connections with the following environment variables:

### PostgreSQL (Application data)

| Environment Variable         | Description                        | Example Value                                   |
| ---------------------------- | ---------------------------------- | ----------------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC URL for PostgreSQL connection | `jdbc:postgresql://postgresql:5432/app_manager` |
| `SPRING_DATASOURCE_USERNAME` | PostgreSQL username                | `flowx`                                         |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL password                | *sensitive*                                     |

### MongoDB (Runtime data)

| Environment Variable      | Description                | Example Value                                                                                                                                                         |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI` | URI for MongoDB connection | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-headless:27017/${DB_NAME}?retryWrites=false` |
| `DB_NAME`                 | MongoDB database name      | `app-runtime`                                                                                                                                                         |
| `DB_USERNAME`             | MongoDB username           | `app-runtime`                                                                                                                                                         |
| `DB_PASSWORD`             | MongoDB password           | *sensitive*                                                                                                                                                           |

## Redis configuration

Runtime Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

## Kafka configuration

### Kafka connection

| Environment Variable             | Description                         | Example Value                      |
| -------------------------------- | ----------------------------------- | ---------------------------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Kafka broker addresses              | `kafka-flowx-kafka-bootstrap:9092` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment prefix for Kafka topics |                                    |

### Kafka OAuth authentication

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Kafka topics

Since the Runtime Manager shares the same container image as the [Application Manager](./application-manager), it uses the same Kafka topic definitions. However, the Runtime Manager conditionally activates a listener for the `build.runtime-data` topic (based on `spring.application.name=runtime-manager`), which is how it receives runtime data from the Admin service.

<Warning>
  The `KAFKA_TOPIC_BUILD_RUNTIMEDATA` topic must resolve to the same value in both Admin and Runtime Manager. If the `KAFKA_TOPIC_NAMING_ENVIRONMENT` prefix differs between services (common after export/import to a new environment), Admin will produce to one topic and Runtime Manager will consume from another, causing data not to be passed back to the calling process after subprocess execution.
</Warning>

#### Build topics

| Environment Variable                            | Description                                                 | Default Pattern                                   |
| ----------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA`                 | Build runtime data topic (consumed only by Runtime Manager) | `ai.flowx.build.runtime-data.v1`                  |
| `KAFKA_TOPIC_BUILD_UPDATE`                      | Build update topic                                          | `ai.flowx.build.update.v1`                        |
| `KAFKA_TOPIC_BUILD_CREATE`                      | Build create topic                                          | `ai.flowx.build.create.v1`                        |
| `KAFKA_TOPIC_BUILD_RESOURCE_EXPORT`             | Build export topic                                          | `ai.flowx.build.export.v1`                        |
| `KAFKA_TOPIC_BUILD_RESOURCE_IMPORT`             | Build import topic                                          | `ai.flowx.build.import.v1`                        |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATES` | Timer events updates topic                                  | `ai.flowx.build.start-timer-events.updates.in.v1` |

#### Consumer configuration

| Environment Variable                                    | Description                               | Default Value                            |
| ------------------------------------------------------- | ----------------------------------------- | ---------------------------------------- |
| `KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA`              | Build runtime data consumer group         | `build-runtime-data-group`               |
| `KAFKA_CONSUMER_GROUPID_BUILD_CREATE`                   | Build create consumer group               | `build-create-group`                     |
| `KAFKA_CONSUMER_GROUPID_BUILD_UPDATE`                   | Build update consumer group               | `build-update-group`                     |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORT`          | Build export consumer group               | `build-resource-export-group`            |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORT`          | Build import consumer group               | `build-resource-import-group`            |
| `KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATES` | Build timer events updates consumer group | `build-start-timer-events-updates-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA`              | Build runtime data consumer threads       | `2`                                      |
| `KAFKA_CONSUMER_THREADS_BUILD_UPDATE`                   | Build update consumer threads             | `4`                                      |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`                      | Auth exception retry interval (seconds)   | `10`                                     |

#### Process topics

| Environment Variable                                | Description                     | Default Pattern                                                     |
| --------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`              | Process start for event topic   | `ai.flowx.core.trigger.start-for-event.process.v1`                  |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN`                | Process start by name topic     | `ai.flowx.core.trigger.start-by-name.process.v1`                    |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT`               | Process start by name out topic | `ai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET`  | Set timer schedule topic        | `ai.flowx.core.trigger.set.timer-event-schedule.v1`                 |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Stop timer schedule topic       | `ai.flowx.core.trigger.stop.timer-event-schedule.v1`                |

#### Other topics

| Environment Variable                    | Description                   | Default Pattern                                  |
| --------------------------------------- | ----------------------------- | ------------------------------------------------ |
| `KAFKA_TOPIC_AUDIT_OUT`                 | Audit topic                   | `ai.flowx.core.trigger.save.audit.v1`            |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Events gateway messages topic | `ai.flowx.eventsgateway.receive.copyresource.v1` |

<Info>
  For the full list of application resource topics (export, import, sync, resource usages, etc.), see the [Application Manager Kafka configuration](./application-manager#kafka-topic-configuration).
</Info>

***

## Authentication configuration

### Security type

| Environment Variable                                      | Description                                                           | Default Value                          |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                       |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                 | Service-accounts realm ID                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80`       |

### Service account configuration

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-runtime-manager-sa`                                                                         |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       | *sensitive*                                                                                        |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               | *sensitive*                                                                                        |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Info>
  The Runtime Manager and the Application Manager are built from the same artifact and share the `flowx-runtime-manager-sa` service account.
</Info>

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

## File storage configuration

| Environment Variable                     | Description                      | Example Value       |
| ---------------------------------------- | -------------------------------- | ------------------- |
| `APPLICATION_FILE_STORAGE_S3_SERVER_URL` | S3-compatible storage server URL | `http://minio:9000` |
| `APPLICATION_FILE_STORAGE_S3_ACCESS_KEY` | S3 access key                    | *sensitive*         |
| `APPLICATION_FILE_STORAGE_S3_SECRET_KEY` | S3 secret key                    | *sensitive*         |

<Info>
  S3-compatible storage is used for storing application files, exports, and imports. The Runtime Manager supports MinIO, AWS S3, and other S3-compatible storage solutions.
</Info>

## Ingress and CORS

The Runtime Manager is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group      | External path                                   | Backend receives                                |
| --------------- | ----------------------------------------------- | ----------------------------------------------- |
| public          | `/rtm/api/runtime`                              | `/api/runtime/...`                              |
| admin           | `/rtm/api/build-mgmt`                           | `/api/build-mgmt/...`                           |
| admin-instances | `/rtm/api/runtime`, `/rtm/api/runtime-internal` | `/api/runtime/...`, `/api/runtime-internal/...` |

All routes strip the `/rtm` prefix before forwarding to the backend. Paths are set through `services.runtime-manager.ingress.<key>.path` (or `gateway.<key>.paths`) in the chart values; the chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` on the admin route by default to support larger application-version uploads. The admin-instances ingress uses a regex pattern (`/rtm/api/(runtime|runtime-internal)`) with a rewrite annotation under Ingress mode; under Gateway API mode the chart renders two separate `PathPrefix` rules instead.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                    | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Runtime Manager. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

> **Note:** Replace placeholders in environment variables with the appropriate values for your environment before starting the service.

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify the PostgreSQL database exists and is accessible
    2. Check that the database user has appropriate permissions
    3. Ensure network connectivity between the pod and PostgreSQL service
    4. Verify the JDBC URL format is correct
    5. For MongoDB, confirm the replica set is healthy and `retryWrites=false` is set in the connection URI
  </Accordion>

  <Accordion title="Kafka publishing failures">
    **Symptoms:** Messages not reaching consumers, runtime data not syncing between Admin and Runtime Manager.

    **Solutions:**

    1. Verify that `KAFKA_TOPIC_BUILD_RUNTIMEDATA` resolves to the same value in both Admin and Runtime Manager
    2. Check that `KAFKA_TOPIC_NAMING_ENVIRONMENT` is consistent across services
    3. Ensure Kafka broker addresses are correct and reachable
    4. Review consumer group IDs for conflicts with other deployments
    5. Check Kafka logs for authorization or connectivity errors
  </Accordion>

  <Accordion title="Service account authentication errors">
    **Symptoms:** 401/403 errors when communicating with other FlowX services.

    **Solutions:**

    1. Verify the Keycloak service account (`flowx-runtime-manager-sa`) is properly configured
    2. Check that client secrets match between configuration and Keycloak
    3. Ensure the service account has required roles assigned
    4. Confirm `SECURITY_TYPE` is set to `jwt-public-key`
    5. Verify the Keycloak base server URL is accessible from the pod
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Application Manager" icon="grid-2" href="./application-manager">
    Companion service sharing the same container image and Helm chart
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Microservices setup guides
Source: https://docs.flowx.ai/5.9/setup-guides/setup-guides-overview

Complete reference for deploying and configuring FlowX.AI microservices in your environment

FlowX.AI is built on a modern microservices architecture, allowing for scalable, resilient, and flexible deployments. Each microservice operates independently while collaborating with others to provide a complete enterprise solution.

## Deployment strategy

Deploying FlowX.AI microservices involves breaking down the application into modular components that can be independently deployed, scaled, and maintained. All microservices are delivered as Docker containers, making them suitable for deployment on any container orchestration platform, such as Kubernetes or Docker Swarm.

### Deployment prerequisites

Before beginning the deployment process, ensure you have:

* A Kubernetes cluster or Docker environment
* Access to a container registry
* Persistent storage for databases
* Network policies configured for inter-service communication
* Resource quotas and limits defined for each environment

### Recommended installation order

<Tip>
  Following the correct installation sequence is crucial for a successful deployment. This ordered approach prevents dependency issues and ensures each service has the required dependencies available when it initializes.
</Tip>

<Steps>
  <Step title="Infrastructure Components">
    First, deploy the foundational infrastructure:

    * **Databases**: PostgreSQL/Oracle for relational data, MongoDB for document storage
    * **Message Broker**: Kafka and ZooKeeper
    * **Caching**: Redis
    * **Identity Management**: Keycloak or other OAuth2 provider
  </Step>

  <Step title="Core Components">
    Next, deploy these core services in order:

    1. **Advancing Controller**: Manages process advancement and orchestration
    2. **Process Engine**: Handles business process execution and state management
  </Step>

  <Step title="Backend Services">
    Once the core components are operational, deploy these services (can be deployed in parallel):

    * **Admin Service**: Platform administration and configuration management
    * **Audit Core**: Compliance auditing and activity tracking
    * **Task Management**: Human task assignment and workflow
    * **Scheduler Core**: Job scheduling and time-based operations
    * **Data Search**: Indexing and searching capabilities
    * **Events Gateway**: Event routing and processing
    * **Document Plugin**: Document generation and management
    * **Notification Plugin**: Communication and alerts management
    * **Any additional plugins or extensions**
  </Step>

  <Step title="AI Platform Services">
    Deploy the AI Platform services for intelligent automation capabilities:

    The AI Platform is a set of Python services:

    * **Planner**: Intent understanding and task orchestration
    * **Agent Builder**: Configuration and runtime for low-code AI nodes
    * **Knowledgebase RAG**: Retrieval-augmented generation over the knowledge base
    * **Embedder**: Embedding generation
    * **Knowledgebase Indexer v2**: Event-driven retrieval-vector indexing
    * **AI Developer**: Automated code generation capabilities
    * **AI Analyst**: Process analysis and optimization
    * **AI Designer**: UI generation and design automation
    * **AI Assistant**: FlowX.AI documentation assistant

    <Note>
      The AI Platform services are optional but provide significant value for organizations looking to use AI capabilities in their business processes.
    </Note>
  </Step>

  <Step title="Frontend Components">
    Finally, deploy the frontend services:

    * **Designer**: Process design environment for business analysts
    * **Web Components**: UI components for custom applications
    * **Customer-facing UIs and portals**
  </Step>
</Steps>

## Environment variables reference

Environment variables are the primary configuration mechanism for FlowX.AI microservices. They provide a secure and flexible way to customize service behavior without modifying the container images.

The following sections detail the most commonly used environment variables across FlowX.AI microservices. For service-specific variables, refer to the dedicated setup guides for each component.

<Warning>
  **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.
</Warning>

### Authorization & access management

| Environment Variable                                | Description                                        | Example Value                       | Required |
| --------------------------------------------------- | -------------------------------------------------- | ----------------------------------- | -------- |
| `SECURITY_OAUTH2_BASESERVERURL`                     | Base URL of the OAuth2/OIDC server                 | `https://keycloak.example.com/auth` | Yes      |
| `SECURITY_OAUTH2_CLIENTCLIENTID`                    | OAuth2 client ID for the service                   | `flowx-admin-service`               | Yes      |
| `SECURITY_OAUTH2_CLIENTCLIENTSECRET`                | OAuth2 client secret                               | `secret`                            | Yes      |
| `SECURITY_OAUTH2_REALM`                             | OAuth2 realm name                                  | `flowx`                             | Yes      |
| `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID`     | Service account client ID (for inter-service auth) | `flowx-service-account`             | No\*     |
| `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET` | Service account client secret                      | `secret`                            | No\*     |

\*Required for some services that need to make authenticated calls to other services

### Database configuration

#### PostgreSQL/Oracle

| Environment Variable                            | Description                     | Example Value                           | Required |
| ----------------------------------------------- | ------------------------------- | --------------------------------------- | -------- |
| `SPRING_DATASOURCE_URL`                         | JDBC connection URL             | `jdbc:postgresql://postgres:5432/flowx` | Yes      |
| `SPRING_DATASOURCE_USERNAME`                    | Database username               | `flowx_user`                            | Yes      |
| `SPRING_DATASOURCE_PASSWORD`                    | Database password               | `securePassword123`                     | Yes      |
| `SPRING_DATASOURCE_DRIVERCLASSNAME`             | JDBC driver class (Oracle only) | `oracle.jdbc.OracleDriver`              | Yes\*    |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULTSCHEMA` | Default schema (Oracle only)    | `FLOWX`                                 | Yes\*    |

\*Required only for Oracle databases

#### MongoDB (NoSQL)

| Environment Variable                  | Description                                | Example Value                                                               | Required |
| ------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- | -------- |
| `SPRING_DATA_MONGODB_URI`             | MongoDB connection URI                     | `mongodb://mongo1,mongo2,mongo3:27017/flowx?replicaSet=rs0`                 | Yes      |
| `DB_USERNAME`                         | MongoDB username for services that need it | `flowx_mongo_user`                                                          | Yes      |
| `DB_PASSWORD`                         | MongoDB password                           | `mongoSecurePass456`                                                        | Yes      |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection          | `true`                                                                      | No       |
| `SPRING_DATA_MONGODB_RUNTIME_URI`     | URI for runtime MongoDB connection         | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-runtime:27017/app-runtime` | No\*     |

\*Required if runtime MongoDB connection is enabled

### Kafka configuration

| Environment Variable               | Description                                       | Example Value                            | Required |
| ---------------------------------- | ------------------------------------------------- | ---------------------------------------- | -------- |
| `KAFKA_BOOTSTRAP_SERVERS`          | Comma-separated list of Kafka brokers (preferred) | `kafka-0:9092,kafka-1:9092,kafka-2:9092` | Yes\*    |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`    | Legacy property for Kafka brokers (fallback)      | `kafka-0:9092,kafka-1:9092,kafka-2:9092` | Yes\*    |
| `KAFKA_SECURITY_PROTOCOL`          | Security protocol for Kafka (preferred)           | `SASL_PLAINTEXT`                         | No       |
| `SPRING_KAFKA_SECURITY_PROTOCOL`   | Legacy property for security protocol (fallback)  | `SASL_PLAINTEXT`                         | No       |
| `SPRING_KAFKA_CONSUMER_GROUPID`    | Consumer group ID                                 | `flowx-process-engine-group`             | Yes      |
| `KAFKA_CONSUMER_THREADS`           | Number of Kafka consumer threads                  | `5`                                      | No       |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions (seconds)      | `10`                                     | No       |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum Kafka message size (bytes)                | `52428800` (50 MB)                       | No       |

<Info>
  The `KAFKA_BOOTSTRAP_SERVERS` and `KAFKA_SECURITY_PROTOCOL` properties are preferred and aligned across all services. The legacy `SPRING_KAFKA_BOOTSTRAPSERVERS` and `SPRING_KAFKA_SECURITY_PROTOCOL` properties remain supported for backwards compatibility. If both are set, the new properties take precedence.

  \*At least one of `KAFKA_BOOTSTRAP_SERVERS` or `SPRING_KAFKA_BOOTSTRAPSERVERS` must be set.
</Info>

#### Kafka authentication profile

FlowX.AI supports enabling Kafka authentication across all Java microservices using the `kafka-auth` Spring configuration profile. This feature simplifies the activation of secure Kafka communication.

To enable Kafka authentication, set the `SPRING_PROFILES_ACTIVE` environment variable:

```bash theme={"system"}
SPRING_PROFILES_ACTIVE=kafka-auth
```

<Info>
  You can activate multiple profiles by separating them with commas: `SPRING_PROFILES_ACTIVE=dev,kafka-auth`
</Info>

**Additional environment variables for OAuth-based Kafka authentication:**

| Environment Variable             | Description                                                    | Example Value                             | Required |
| -------------------------------- | -------------------------------------------------------------- | ----------------------------------------- | -------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID used to authenticate with the token endpoint   | `kafka-client`                            | Yes\*    |
| `KAFKA_OAUTH_CLIENT_SECRET`      | Secret associated with the OAuth client ID                     | `kafka-secret`                            | Yes\*    |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint URI from which access tokens are obtained | `https://keycloak.example.com/auth/token` | Yes\*    |

\*Required when `kafka-auth` profile is active

<Warning>
  The kafka-auth profile enforces SASL/OAUTHBEARER with plaintext transport. Ensure secure networking (VPN, mTLS) is configured where required.
</Warning>

For more details, see the [Kafka Authentication Configuration](./kafka-authentication-config) guide.

### Redis configuration

FlowX.AI microservices use Redis for caching and real-time data management. Redis can be deployed in three modes: Standalone, Sentinel (high availability), and Cluster (horizontal scaling).

**Quick reference for common Redis variables:**

| Environment Variable                | Description                   | Example Value             | Mode       |
| ----------------------------------- | ----------------------------- | ------------------------- | ---------- |
| `SPRING_DATA_REDIS_HOST`            | Redis server hostname         | `localhost`               | Standalone |
| `SPRING_DATA_REDIS_PORT`            | Redis server port             | `6379`                    | Standalone |
| `SPRING_DATA_REDIS_PASSWORD`        | Redis authentication password | `yourpassword`            | All modes  |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Sentinel master name          | `mymaster`                | Sentinel   |
| `SPRING_DATA_REDIS_SENTINEL_NODES`  | Sentinel nodes list           | `host1:26379,host2:26379` | Sentinel   |
| `SPRING_DATA_REDIS_CLUSTER_NODES`   | Cluster nodes list            | `host1:6379,host2:6379`   | Cluster    |

<Info>
  For complete Redis configuration including all deployment modes, SSL/TLS setup, and troubleshooting, see the [Redis Configuration](./redis-configuration) guide.
</Info>

### Logging configuration

| Environment Variable         | Description                        | Default Value | Required |
| ---------------------------- | ---------------------------------- | ------------- | -------- |
| `LOGGING_LEVEL_ROOT`         | Root logging level                 | `INFO`        | No       |
| `LOGGING_LEVEL_APP`          | Application-specific logging level | `DEBUG`       | No       |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver logging level       | `WARN`        | No       |
| `LOGGING_LEVEL_KAFKA`        | Kafka client logging level         | `WARN`        | No       |
| `LOGGING_LEVEL_REDIS`        | Redis client logging level         | `OFF`         | No       |

#### Changing log levels at runtime

All FlowX microservices support dynamic log level adjustment without requiring a restart. This capability uses Spring Boot Actuator's loggers endpoint and is particularly useful for troubleshooting production issues.

**Prerequisites:**

Ensure the `loggers` endpoint is exposed in your management endpoints configuration:

**Example usage:**

```bash theme={"system"}
curl 'http://localhost:8081/manage/actuator/loggers/ai.flowx' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
```

Replace `ai.flowx` with the specific logger package you want to modify.

**Available log levels:** `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

<Warning>
  Dynamic log level changes are not persisted. They will reset to the configured values when the service restarts. Using `DEBUG` or `TRACE` levels in production may impact performance and generate large log volumes.
</Warning>

## Deployment best practices

### High availability considerations

For production environments, configure these high availability features:

* **Database Clustering**: Implement PostgreSQL/Oracle with replication
* **MongoDB Replica Sets**: Deploy MongoDB as a replica set with at least 3 nodes
* **Kafka Clustering**: Use at least 3 Kafka brokers with replication factor ≥ 3
* **Redis Sentinel/Cluster**: Configure Redis for high availability
* **Service Replicas**: Run multiple instances of each microservice
* **Load Balancing**: Implement proper load balancing for service instances
* **Affinity/Anti-Affinity Rules**: Distribute service instances across nodes

### Security recommendations

Secure your FlowX.AI deployment with these measures:

1. **Network Segmentation**: Isolate microservices using network policies
2. **Secret Management**: Use Kubernetes Secrets or a vault solution
3. **TLS Everywhere**: Enable TLS for all service-to-service communication
4. **OAuth2 Scopes**: Configure fine-grained OAuth2 scopes for services
5. **Resource Isolation**: Use namespaces and pod security policies
6. **Regular Updates**: Keep all components updated with security patches
7. **Audit Logging**: Enable comprehensive audit logging via the Audit Core service

## Troubleshooting

### Common issues and solutions

| Issue                      | Possible cause                | Solution                                                        |
| -------------------------- | ----------------------------- | --------------------------------------------------------------- |
| Service fails to start     | Missing environment variables | Check logs for "Configuration property not found" errors        |
| Database connection errors | Incorrect credentials or URL  | Verify database connection parameters                           |
| Services can't communicate | Kafka misconfiguration        | Ensure topic names match between producer and consumer services |
| Authentication failures    | OAuth2 configuration issues   | Verify client IDs, secrets, and server URLs                     |
| Performance degradation    | Insufficient resources        | Monitor CPU/memory usage and scale resources appropriately      |
| Data inconsistency         | Redis cache not synchronized  | Check Redis connection and consider cache invalidation          |

### Diagnostic procedures

When troubleshooting FlowX.AI microservices:

1. **Check Service Logs**: Examine logs for error messages
2. **Verify Configurations**: Ensure all required environment variables are set correctly
3. **Test Connectivity**: Verify network connectivity between services
4. **Monitor Resources**: Check CPU, memory, and disk usage
5. **Inspect Kafka Topics**: Use Kafka tools to inspect message flow
6. **Review Database State**: Examine database for data integrity issues
7. **Check OAuth2 Tokens**: Verify token validity and permissions

## Service-specific documentation

For detailed configuration of individual services, refer to:

### Core platform components

<CardGroup>
  <Card title="Process Engine Setup" href="../setup-guides/flowx-engine-setup-guide/engine-setup" icon="gear" />

  <Card title="Admin Setup" href="../setup-guides/admin-setup-guide" icon="shield" />

  <Card title="Advancing Controller Setup" href="../setup-guides/advancing-controller-setup-guide" icon="gear" />

  <Card title="Application Manager Setup" href="../setup-guides/application-manager" icon="gear" />

  <Card title="Runtime Manager Setup" href="../setup-guides/runtime-manager" icon="database" />

  <Card title="Scheduler Core Setup" href="../setup-guides/scheduler-setup-guide" icon="clock" />

  <Card title="Audit Setup" href="../setup-guides/audit-setup-guide" icon="clipboard-list" />

  <Card title="Authorization Setup" href="../setup-guides/authorization-setup-guide" icon="key" />

  <Card title="Task Management Setup" href="../setup-guides/task-management-plugin-setup" icon="list-check" />

  <Card title="Notifications Setup" href="../setup-guides/notifications-plugin-setup" icon="envelope" />

  <Card title="Document Setup" href="../setup-guides/documents-plugin-setup" icon="file" />

  <Card title="Events Gateway Setup" href="../setup-guides/events-gateway-setup" icon="envelope" />
</CardGroup>

### AI Platform services

<Info>
  The AI Platform is a suite of AI services that provide intelligent automation capabilities across the entire application lifecycle.
</Info>

<Card title="AI Platform Setup" href="../ai-platform/ai-platform-setup" icon="robot" />

### Plugins & extensions

<CardGroup>
  <Card title="OCR Plugin Setup" href="../setup-guides/plugins-setup-guide/ocr-plugin-setup" icon="scan-line" />

  <Card title="Reporting Setup" href="../setup-guides/plugins-setup-guide/reporting-setup" icon="chart-bar" />
</CardGroup>

### Integration & data services

<CardGroup>
  <Card title="Integration Designer Setup" href="../setup-guides/integration-designer-setup" icon="puzzle-piece" />

  <Card title="Data Search Setup" href="../setup-guides/search-data-service-setup-guide" icon="magnifying-glass" />

  <Card title="Data Sync Setup" href="../setup-guides/data-sync" icon="arrows-rotate" />

  <Card title="NoSQL DB Runner Setup" href="../setup-guides/nosql-db-runner" icon="database" />
</CardGroup>

### User interface & designer

<CardGroup>
  <Card title="Designer Setup" href="../setup-guides/designer-setup-guide" icon="palette" />

  <Card title="CMS Setup" href="../setup-guides/cms-setup" icon="file" />
</CardGroup>

### Infrastructure & extensions

<CardGroup>
  <Card title="SpiceDB Setup" href="../setup-guides/spicedb" icon="shield-check" />
</CardGroup>

### Observability & configuration

<CardGroup>
  <Card title="OpenTelemetry Config" href="../setup-guides/open-telemetry-config" icon="chart-line" />

  <Card title="OT Default Properties" href="../setup-guides/ot-default-properties" icon="scroll" />
</CardGroup>


# Android SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/android

Migrate the FlowX Android renderer SDK from 5.1.x LTS to 5.9.x.

## Android SDK migration guide

### SDK API changes

#### Config

The `Config` interface used when initializing the SDK now requires a new, mandatory, property, named `organizationId` (the ID of the organization used to identify your installation):

```kotlin diff 5.1.x LTS..5.9.x version theme={"system"}
Flowx.getInstance().init(
    ...
    config = object : Config {
        override val organizationId: String = "organization id" // [!code ++]
        override val baseUrl = "URL to FlowX backend",
        override val imageBaseUrl = "URL to FlowX CMS Media Library",
        override val enginePath = "some_path",
        override val language = "en",
        override val locale = Locale.getDefault(),
        override val validators: Map<String, (String) -> Boolean>? = mapOf("exact_25_in_length" to { it.length == 25 }),
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE,
    },
    ...
)
```

#### Custom loaders

The `CustomLoaderProvider` interface has been changed from:

```kotlin 5.1.x LTS version theme={"system"}
interface CustomLoaderProvider {
    fun provideCustomLoader(actionName: String?): CustomLoader?
}
```

to

```kotlin 5.9.x version theme={"system"}
interface CustomLoaderProvider {
    fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader?
}
```

where the `CustomLoaderProvider.LoaderType` is defined like this:

```kotlin theme={"system"}
interface LoaderType {
    interface StartProcess : LoaderType
    interface ReloadProcess : LoaderType
    interface Action : LoaderType { val name: String }
    interface Upload : LoaderType { val name: String }
}
```

<Info>
  The available types for the `loaderType` parameter are:

  * `LoaderType.StartProcess` - received for overriding the loader displayed when starting a new process
  * `LoaderType.ReloadProcess` - received for overriding the loader displayed when resuming an existing process
  * `LoaderType.Action` - received for overriding the loader displayed while the action having the `name` name is executed
  * `LoaderType.Upload` - received for overriding the loader displayed while the **upload** action having the `name` name is executed

  The `name` property received for the `LoaderType.Action` and `LoaderType.Upload` types represents the name of an action, as defined at process definition time, received for being able to override the loader displayed while that action is executed.
</Info>

<Info>
  Returning an implementation of a `CustomLoader` replaces the built-in platform loader with the provided one for the specified use cases.<br /><br />
  Returning `null` keeps the built-in platform loader for the specified use cases.
</Info>

## Related resources

<CardGroup>
  <Card title="Android SDK reference" icon="android" href="/5.9/sdks/android-renderer">
    Android renderer SDK documentation
  </Card>

  <Card title="Migration overview" icon="arrow-up-right-from-square" href="./overview">
    Return to the 5.1 LTS → 5.9 LTS migration hub
  </Card>
</CardGroup>


# Angular SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/angular

Migrate the FlowX Angular renderer SDK from 5.1.x LTS to 5.9.x.

## Angular SDK migration guide

5.9 bumps the Angular renderer to Angular 20. A new required input is introduced on `<flx-process-renderer>`, one legacy input is removed, and two top-level props are added.

### Framework upgrade: Angular 19 → 20

Upgrade your host app to Angular 20 **before** bumping the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) with `from: 19.0` and `to: 20.0`.

| Requirement | 5.1      | 5.9          |
| ----------- | -------- | ------------ |
| Angular CLI | \~19.2   | **\~20**     |
| Node        | ≥ 20.9.0 | **≥ 24.0.0** |
| npm         | ≥ 10.1.0 | **≥ 11.0.0** |
| TypeScript  | \~5.5    | **≥ 5.8**    |

### FlowX SDK changes

#### Organization ID property

We've added a new `organizationId` mandatory input to the `<flx-process-renderer>` component. See SDK documentation for more details.

```html theme={"system"}
<flx-process-renderer
  ...
  [organizationId]="'10000001-0001-0001-8001-100000000001'"
/>
```

#### `keepState` removed

The `[keepState]` input was removed in 5.9. Process data is always reset when the component is destroyed.

```diff theme={"system"}
- [keepState]="keepState"
```

## Related resources

<CardGroup>
  <Card title="Angular SDK reference" icon="angular" href="/5.9/sdks/angular-renderer">
    Angular renderer SDK documentation
  </Card>

  <Card title="Migration overview" icon="arrow-up-right-from-square" href="./overview">
    Full 5.1.x LTS → 5.9.x upgrade guide
  </Card>
</CardGroup>


# API & integration breaking changes
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/api-breaking-changes

REST endpoint renames, removals, mandatory headers, and token-format changes that custom API clients and integrations must adapt to between 5.1.x and 5.9.x.

5.1.x deployments expose a stable surface of REST endpoints that internal Designer and renderer code, custom integrations, and direct API consumers depend on. The 5.1 → 5.9 jump introduces four REST-surface changes that custom callers must adapt to: one endpoint rename, one feature removal, one new mandatory request header, and one authentication-token-format change. None of these affect Designer or the FlowX-shipped renderer SDKs. Those are managed automatically when you upgrade. The audit work is for whatever calls FlowX from outside.

A fifth change is internal to the platform but affects the runtime behavior of existing JavaScript and Python scripts: the default script execution engine moves from GraalVM polyglot contexts to a native Node.js + CPython subprocess pool. Most scripts keep working unchanged; a small subset that relied on GraalVM-specific behavior must be adapted, or kept on GraalVM via an opt-out env var.

<Info>
  If your deployment only uses FlowX through Designer and the shipped renderer SDKs, you can skim this page. If you have **custom API clients, custom integrations, or scripts that call the FlowX REST API directly**, or if you wrote **JavaScript or Python business rules / workflow scripts** in your project, work through every section.
</Info>

***

## Process start metadata endpoint renamed

The endpoint that returns the JSON shape required to start a process was renamed and its response extended.

| Before (5.1.x)                                      | After (5.9.x)                                           |
| --------------------------------------------------- | ------------------------------------------------------- |
| `GET /api/process-definition/{uuid}/get-input-json` | `GET /api/process-definition/{uuid}/get-start-metadata` |

The response gains a `hasEmailTriggerStart` boolean field that tells the caller whether the process can be started by an inbound email trigger. Existing response fields are unchanged.

Update any direct API clients, Postman collections, scripts, or upstream integration code that hard-codes the old path. The old path returns a 404 after upgrade.

***

## Configure Environment Info feature deprecated

The Configure Environment Info feature, which let operators set a human-readable environment name (Dev / Staging / Production) from the Designer Platform Status page, is deprecated. Environment name now comes from organization registration and workspace types instead.

### `PATCH /api/platform/environment` endpoint removed

The endpoint that updated the environment name is removed. Any caller that issues a `PATCH` against this path receives a 404.

### `environmentDetails` field in `/api/init` is deprecated

The `environmentDetails` block in the `/api/init` response is deprecated. Designer no longer reads it, and new clients should switch to the dedicated `/env` endpoint. The field is still present in the response during the deprecation window for backward compatibility, but direct API consumers should treat it as a stale source and migrate.

### Environment-name env vars no longer used

The following environment variables are no longer consumed by any service and should be removed from your deployment manifests during the upgrade:

| Removed env var          | Replacement                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `FLOWX_CLIENT_NAME`      | Organization name set during registration                        |
| `FLOWX_ENVIRONMENT_NAME` | Workspace type (Sandbox / Staging / Production) on the workspace |

See [Organization & deployment configuration](./organization-deployment) for organization registration and workspace types.

***

## `Fx-Organization-Id` header mandatory for REST clients

Self-hosted deployments now run in single-organization mode by default. Every REST request that targets an organization-scoped endpoint must include the organization UUID as a request header:

```http theme={"system"}
Fx-Organization-Id: <your-organization-uuid>
```

The header is required on every organization-scoped REST endpoint: process runtime, task management, document plugin, audit query, and any other endpoint that returns data scoped to your organization. Without the header, requests fail with a client error before reaching the business logic. Designer and the FlowX renderer SDKs set the header automatically from the current session. The audit applies to custom callers only.

If you have custom integrations that span multiple endpoint surfaces, your FlowX representative can confirm which specific endpoints in your integration pattern require the header before you start the upgrade.

Your FlowX representative provides the organization UUID during the upgrade. See [Organization & deployment configuration](./organization-deployment) for where to obtain it and [Kafka migration](./kafka) for the matching Kafka-side header rule.

***

## Script runtime change for JavaScript and Python business rules

The default execution engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a native subprocess pool (Node.js for JavaScript, CPython 3.11 for Python). The change is transparent for the vast majority of scripts, but a small subset that relied on GraalVM-specific behavior must be adapted, or kept on GraalVM via an opt-out environment variable.

| Aspect                                                                  | Before (5.1.x)                      | After (5.9.x)                                                                                                                                                                                                       |
| ----------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JavaScript runtime                                                      | GraalJS on GraalVM 24.x             | Node.js V8                                                                                                                                                                                                          |
| Python runtime                                                          | GraalPy on GraalVM 24.x             | CPython 3.11                                                                                                                                                                                                        |
| `input` / `output` / `additionalData` / `instanceMetadata` bindings     | Available                           | Available, unchanged                                                                                                                                                                                                |
| `output.put(...)` / `output.get(...)` / `output.containsKey(...)`       | Java HashMap methods                | Preserved on both JavaScript and Python                                                                                                                                                                             |
| Python `import` of arbitrary stdlib                                     | Allowed                             | Curated allowlist: `random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64` are pre-loaded and ready to use; other modules are blocked |
| JavaScript `require(...)` / `process` / `global`                        | Worked via GraalVM polyglot context | Not available; scripts run in an isolated V8 context with an explicit globals allowlist                                                                                                                             |
| Calling Java classes from scripts (`Java.type(...)`, polyglot bindings) | Worked via GraalVM                  | Not available on the native engine                                                                                                                                                                                  |

### What you do not need to change

Scripts that only read from `input`, write to `output`, and use language built-ins (object/dict access, arithmetic, string methods, JSON, the pre-loaded Python modules above) keep working without modification.

### What to audit before upgrading

1. **Python `import` statements.** Search Python business-rule and workflow scripts for `import` lines that pull in modules outside the curated allowlist above. Narrow the script to use only allowed modules, or plan to stay on GraalVM via the opt-out env var below.
2. **JavaScript `require(...)`, `process`, `global` references.** Search JavaScript scripts for these tokens. They were not officially part of the supported surface area but may have worked under GraalVM. Rewrite to use only the provided bindings, or stay on GraalVM.
3. **Polyglot calls into Java classes.** Search for `Java.type`, `java.util.`, `org.springframework.` in scripts. These only worked under GraalVM and have no equivalent on the native engine. Stay on GraalVM if you depend on them.

### How to keep the GraalVM engine

Set the following on both `process-engine` and `integration-designer`:

```yaml theme={"system"}
APPLICATION_SCRIPTENGINE_PROVIDER: graalvm
```

GraalVM is bundled and supported alongside the native engine. Use this as a transitional setting while you adapt scripts, or as a permanent setting if you have a strong reason to keep polyglot behavior.

See [Native script engine for JavaScript and Python](/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026#native-script-engine-for-javascript-and-python) in the 5.9.0 release notes for the full feature card.

***

## Direct API clients using opaque tokens must switch to JWT

FlowX services moved to validating signed JWT bearer tokens against Keycloak's public key. Opaque reference tokens, session cookies, and other non-JWT bearer strings are no longer accepted as the default and may not be supported at all on the affected services. Confirm with your FlowX representative if your integrations rely on them.

This change is transparent for callers that already use JWT bearer tokens issued by Keycloak (Designer, renderer SDKs, anything using the standard OIDC flow). It only affects **direct API clients** that obtain non-JWT credentials.

Such clients must obtain a signed JWT access token from Keycloak (standard `client_credentials` or `password` grants returning a JWT) and pass it as `Authorization: Bearer <jwt>`.

See [Authentication & IAM migration](./authentication-iam) for the full Keycloak two-realm architecture and the service-account client renames that go alongside this change.

***

## Pre-upgrade audit

For each of your custom API clients and integrations, confirm:

<Steps>
  <Step title="Endpoint paths">
    Search your codebase, Postman collections, API gateway rules, and shell scripts for the strings `get-input-json` and `/api/platform/environment`. Update the first to `get-start-metadata`; remove any `PATCH` calls to the second.
  </Step>

  <Step title="Environment-name reads">
    Search for callers that parse the `environmentDetails` block out of `/api/init`. Plan their migration to the `/env` endpoint.
  </Step>

  <Step title="Request headers">
    Confirm every REST call from custom code includes `Fx-Organization-Id`. Add it via your HTTP client's default-header configuration if not already centralized.
  </Step>

  <Step title="Token format">
    Confirm every custom API client uses a JWT bearer token from Keycloak. Not an opaque reference token, session cookie, or API key. Update token-acquisition code if necessary.
  </Step>

  <Step title="Environment-name env vars">
    Remove `FLOWX_CLIENT_NAME` and `FLOWX_ENVIRONMENT_NAME` from Helm values, deployment manifests, and any out-of-band env files. They are silently ignored on 5.9.x.
  </Step>

  <Step title="JavaScript and Python scripts">
    Search business-rule and workflow scripts for: Python `import` statements pulling modules outside the curated allowlist; JavaScript `require(...)`, `process`, or `global` references; calls into Java classes (`Java.type`, `java.util.`, `org.springframework.`). Adapt the scripts or set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine.
  </Step>
</Steps>

***

## Related resources

<CardGroup>
  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Keycloak two-realm architecture, service-account client renames, opaque-token removal.
  </Card>

  <Card title="Organization & deployment configuration" icon="building-shield" href="./organization-deployment">
    Organization UUID, single-org default mode, removed env-info env vars.
  </Card>

  <Card title="Kafka migration" icon="message" href="./kafka">
    `Fx-Organization-Id` on Kafka producers; new topics and ownership moves.
  </Card>

  <Card title="Migration overview" icon="arrow-up-right-from-square" href="./overview">
    Return to the migration hub.
  </Card>
</CardGroup>


# Authentication & IAM migration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/authentication-iam

Keycloak two-realm architecture, service-account renames, opaque-token removal, and the new env vars required on 5.9.x.

Authentication is the single largest break in the 5.1 → 5.9 upgrade. The model changes in three coordinated areas: service-account client naming, two-realm architecture, and JWT token validation. 5.1.x customers absorb the full transition during the upgrade.

<Warning>
  **Hard prerequisite for booting any 5.9.x service.** All FlowX services validate access tokens against the new Keycloak two-realm architecture and reject the legacy opaque-token + per-service realm configuration. Plan this section before the upgrade window. Services will not start with 5.1.x auth env vars left in place.
</Warning>

***

## What changed at the platform level

| Concern                           | 5.1.x                                       | 5.9.x                                                        |
| --------------------------------- | ------------------------------------------- | ------------------------------------------------------------ |
| Token validation                  | Opaque-token introspection against Keycloak | JWT public-key validation (`SECURITY_TYPE: jwt-public-key`)  |
| Service-account client naming     | Per-service ad-hoc names                    | Standardized `flowx-{service-name}-sa` pattern               |
| Realm architecture                | Single Keycloak realm                       | Two realms — user realm + dedicated service-accounts realm   |
| Service-accounts realm UUID       | n/a                                         | `00000002-0002-4002-8002-000000000002`                       |
| `flowx-platform-authorize` client | Used for legacy token introspection         | Removed — no longer needed                                   |
| SMTP                              | Optional                                    | Required in Keycloak for password reset and user invitations |

***

## Service-account client renames

Every FlowX service authenticates to Keycloak through a service-account client. On 5.9.x these clients all follow the `flowx-{service-name}-sa` pattern, in the dedicated service-accounts realm (`00000002-0002-4002-8002-000000000002`).

On a 5.1 → 5.9 upgrade, **the `authorization-system` service migrates the existing `flowx` realm and provisions the new service-accounts realm at first boot**, including the clients below. The list is provided as a verification reference and as the source list for the Manual Keycloak Configuration path.

| Client ID                         | Used by                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flowx-admin-sa`                  | admin                                                                                                                                                                                                                                                                                                                                             |
| `flowx-process-engine-sa`         | process-engine                                                                                                                                                                                                                                                                                                                                    |
| `flowx-integration-designer-sa`   | integration-designer                                                                                                                                                                                                                                                                                                                              |
| `flowx-authorization-system-sa`   | authorization-system                                                                                                                                                                                                                                                                                                                              |
| `flowx-runtime-manager-sa`        | runtime-manager                                                                                                                                                                                                                                                                                                                                   |
| `flowx-scheduler-core-sa`         | scheduler-core                                                                                                                                                                                                                                                                                                                                    |
| `flowx-task-management-plugin-sa` | task-management-plugin                                                                                                                                                                                                                                                                                                                            |
| `flowx-organization-manager-sa`   | organization-manager                                                                                                                                                                                                                                                                                                                              |
| `flowx-email-gateway-sa`          | email-gateway                                                                                                                                                                                                                                                                                                                                     |
| `flowx-license-sa`                | license                                                                                                                                                                                                                                                                                                                                           |
| `flowx-webhook-gateway-sa`        | webhook-gateway                                                                                                                                                                                                                                                                                                                                   |
| `flowx-file-gateway-sa`           | file-gateway                                                                                                                                                                                                                                                                                                                                      |
| `flowx-anonymous-sa`              | admin, application-manager, authorization-system, document-plugin, email-gateway, events-gateway, file-gateway, integration-designer, license, mock-server, nosql-db-runner, organization-manager, process-engine, scheduler-core, task-management-plugin, webhook-gateway — for inter-service calls on anonymous (unauthenticated) runtime flows |

<Note>
  **`flowx-anonymous-sa` uses a dedicated, low-privilege realm role.** Unlike the other service-account clients above, this one is **not** assigned `SA_FLOWX`. The migration creates a new `SA_FLOWX_ANONYMOUS` realm role in the service-accounts realm and assigns it only that role. This caps the blast radius if the token leaks: an attacker can only invoke endpoints reachable to an anonymous internet visitor on processes or UI flows that explicitly opted into the `Anonymous` runtime role.
</Note>

<Info>
  **Manual Keycloak Configuration path.** If your environment does not allow FlowX to administer Keycloak directly (for example, restricted enterprise deployments), follow the Manual Keycloak Configuration recipe. See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for the complete realm, client, and mapper setup.
</Info>

***

## Remove legacy authentication env vars

Strip the following from every service's Helm values / env files. These belong to the opaque-token introspection model and will prevent services from starting on 5.9.x.

| Environment Variable                                                 | Affected services |
| -------------------------------------------------------------------- | ----------------- |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_INTROSPECTIONURI` | 14 services       |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTID`         | 14 services       |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTSECRET`     | 14 services       |
| `SECURITY_OAUTH2_REALM`                                              | 14 services       |
| `SECURITY_OAUTH2_CLIENT_CLIENTID`                                    | 14 services       |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`                                | 14 services       |
| `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID`                      | 8 services        |
| `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET`                  | 8 services        |

### Deprecated env vars (still consumed for backward compatibility)

The following env vars are deprecated on 5.9.x. Their values are now populated by organization registration. Existing deployments can leave them set during the upgrade window, but plan to remove them once organization registration is complete.

| Environment Variable     | Affected services | Replaced by                                                      |
| ------------------------ | ----------------- | ---------------------------------------------------------------- |
| `FLOWX_CLIENT_NAME`      | admin             | Registered organization code (`DEFAULT_ORGANIZATION_NAME`)       |
| `FLOWX_ENVIRONMENT_NAME` | admin             | Captured during organization registration; no env var equivalent |

<Warning>
  **`flowx-platform-authorize` Keycloak client.** This client was used for legacy authorization paths and is no longer referenced anywhere in 5.9.x. Delete it from your Keycloak configuration after the upgrade completes.
</Warning>

***

## New required env vars

Add the following across all services. Defaults shown are the canonical 5.9.x defaults. Override only when your environment requires a different value.

### On every service (19 of 19)

| Environment Variable                                      | Description                                                      | Default Value                          |
| --------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism. Replaces opaque-token introspection. | `jwt-public-key`                       |
| `SECURITY_OAUTH2_SAREALM`                                 | Realm UUID for service-to-service authentication.                | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service.                         | `-` (set per deployment)               |

<Warning>
  **Set `SECURITY_TYPE` explicitly on every service — do not rely on a chart default.** JWT validation only activates when `SECURITY_TYPE` is set to `jwt-public-key`. The legacy opaque-token mode runs under `SECURITY_TYPE: oauth2`. If your Helm values, or a wrapper chart layered on top of the FlowX chart, leave `SECURITY_TYPE` unset, services keep validating tokens with opaque-token introspection and authentication fails against the 5.9.x two-realm setup. Set `jwt-public-key` on all 19 services as part of the upgrade.
</Warning>

<Info>
  `ORGANIZATION_ID` is **not** required on every service. Only on the 9 services that backfill `organization_id` columns via Liquibase (`application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`). The `license` service consumes the same UUID through a separate env var, `FLOWX_LICENSE_ORGANIZATIONID`. See [Organization & deployment configuration](./organization-deployment#organization_id--where-it-is-actually-required) for the exact behavior across fresh-install vs upgrade scenarios.
</Info>

### On the 8 services that initiate service-to-service calls

These services have a `MAINIDENTITY` client registration that follows the new service-account naming convention.

| Environment Variable                                                   | New Default                                                                        |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`     | `flowx-${spring.application.name}-sa`                                              |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | `-` (Keycloak-issued)                                                              |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`     | Now references `${security.oauth2.sa-realm}` instead of `${security.oauth2.realm}` |

### On `authorization-system` (master-realm administration)

By default, the authorization-system performs realm migrations on startup and needs master-realm admin credentials. This behavior is controlled by `SECURITY_KEYCLOAKADMINENABLED`, which defaults to `true` (FlowX administers Keycloak).

| Environment Variable                  | Description                                                                                                                                                                                                   | Default Value |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `SECURITY_KEYCLOAKADMINENABLED`       | Whether FlowX has Keycloak admin access and manages realms itself. Set to `false` if your environment does not grant FlowX admin access — the `SECURITY_MASTERREALM_*` variables below are then not required. | `true`        |
| `SECURITY_MASTERREALM_ADMIN_CLIENTID` | Master-realm admin client.                                                                                                                                                                                    | `admin-cli`   |
| `SECURITY_MASTERREALM_NAME`           | Master realm name.                                                                                                                                                                                            | `master`      |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Master-realm admin username.                                                                                                                                                                                  | `-`           |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Master-realm admin password. Store in a Secret.                                                                                                                                                               | `-`           |

The admin user supplied here must hold the **Admin** role on the master realm with permission to create realms — the migrations provision a new user realm and a service-accounts realm at first boot, and they also create clients, users, and service accounts in those realms.

<Note>
  When `SECURITY_KEYCLOAKADMINENABLED=false`, FlowX does not manage Keycloak realms and the `SECURITY_MASTERREALM_*` credentials are not needed. Use the Manual Keycloak Configuration path to create the realms and service accounts yourself. The same flag governs the `data-sync` master-realm credentials below.
</Note>

Service-account client secrets for the service-accounts realm must also be supplied as Liquibase parameters on `authorization-system`. One per service, via `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICE_ACCOUNTS_FLOWX_*_SA` (13 secrets in total, matching the service-account clients listed above).

<Warning>
  **Missing SA secrets fail silently.** If `SECURITY_MASTERREALM_ADMIN_PASSWORD` is missing, the service refuses to start. Easy to diagnose. If individual `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICE_ACCOUNTS_FLOWX_*_SA` values are missing, the realm-migration changeset logs an error but the service starts; the SA realm ends up half-populated, and service-to-service authentication breaks at runtime. Verify all 13 secrets are set before booting 5.9.x.
</Warning>

### On `data-sync` (runtime authorization migration)

The runtime-authorization migration step in `data-sync` connects directly to Keycloak to refresh runtime user/group/role assignments. Configure the same master-realm admin credentials on `data-sync`:

| Environment Variable     | Description                                                                  | Default Value |
| ------------------------ | ---------------------------------------------------------------------------- | ------------- |
| `FLOWX_OPENID_PROVIDER`  | Identity provider type.                                                      | `keycloak`    |
| `FLOWX_OPENID_SERVERURL` | Keycloak base URL — same as `SECURITY_OAUTH2_PUBLIC_SERVER_URL`.             | `-`           |
| `FLOWX_OPENID_USER`      | Master-realm admin username — same as `SECURITY_MASTERREALM_ADMIN_USERNAME`. | `admin`       |
| `FLOWX_OPENID_PASSWORD`  | Master-realm admin password — same as `SECURITY_MASTERREALM_ADMIN_PASSWORD`. | `-`           |
| `FLOWX_OPENID_CLIENTID`  | Master-realm admin client — same as `SECURITY_MASTERREALM_ADMIN_CLIENTID`.   | `admin-cli`   |

<Info>
  These reuse the master-realm admin you set on `authorization-system`. They are required for the runtime-authorization migration to complete; without them, `data-sync` cannot refresh runtime role assignments and post-migration login validation fails.
</Info>

***

## Configure SMTP in Keycloak

On 5.9.x, Keycloak is the system of record for password resets and user invitations. Configure an SMTP server on each Keycloak realm that will issue invitations. At minimum the user realm. Without SMTP, invitations and password-reset flows fail silently.

See your Keycloak documentation for the realm-level SMTP settings (host, port, encryption, sender address, credentials). FlowX-issued invitation emails are templated by Keycloak.

***

## What happens to existing tokens and sessions

* **Existing user sessions** are invalidated by the realm transition. Users must sign in again after the upgrade.
* **Existing service-account tokens** are invalidated. The new `flowx-{service}-sa` clients re-establish service-to-service authentication on first request.
* **Existing API tokens issued to integration partners** must be re-issued from the new service-accounts realm.

Plan the upgrade window with a clean post-upgrade login + re-issue pass.

***

## Verify the configuration

After services boot on 5.9.x, confirm:

<Check>
  The two Keycloak realms exist. User realm + service-accounts realm (`00000002-0002-4002-8002-000000000002`).
</Check>

<Check>
  Every service-account client listed above exists in the service-accounts realm and has client credentials configured.
</Check>

<Check>
  All services started cleanly. Service logs show JWT validation rather than opaque-token introspection. Search for `jwt-public-key` in startup logs.
</Check>

<Check>
  Test user sign-in completes end to end against the user realm.
</Check>

<Check>
  Test password-reset email arrives (validates Keycloak SMTP).
</Check>

***

## Related resources

<CardGroup>
  <Card title="Configuring an IAM solution" icon="key" href="/5.9/setup-guides/access-management/configuring-an-iam-solution">
    Full Keycloak realm, client, and mapper setup, including the Manual Keycloak Configuration recipe.
  </Card>

  <Card title="Access Management overview" icon="users-gear" href="/5.9/setup-guides/access-management/access-management-overview">
    How authentication and authorization fit together in 5.9.x.
  </Card>

  <Card title="Runtime authorization migration" icon="shield-halved" href="./runtime-authorization">
    Next step. The runtime authorization rewrite that depends on this auth foundation.
  </Card>

  <Card title="Organization & deployment configuration" icon="building-shield" href="./organization-deployment">
    `ORGANIZATION_ID` propagation and the new `license` service.
  </Card>
</CardGroup>


# Engine partitioning configuration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/engine-partitioning

The process-instance partitioning and archiving configuration consolidated under flowx.data.partitioning.archiving. This page maps the old 5.1.x keys to the 5.9.x structure.

## Who this affects

Only deployments that had **data partitioning enabled** on 5.1.x. If you never set `FLOWX_DATA_PARTITIONING_ENABLED=true`, there is nothing to migrate — the defaults are unchanged and partitioning stays off.

If you did use partitioning, the configuration shape changed between 5.1.x and 5.9.x. You must rename your settings before the upgrade; the old keys no longer bind.

***

## What changed

In 5.1.x, partitioning settings and the archiving scheduler lived in **two separate blocks** — `flowx.data.partitioning.*` for partitioning and a standalone `scheduler.dataPartitioning.*` block for the archiving cron job.

In 5.9.x, everything is consolidated under a single `flowx.data.partitioning` block, with all archiving settings nested in an `archiving` sub-block. The standalone `SCHEDULER_DATA_PARTITIONING_*` variables no longer exist.

<Warning>
  **This is a hard cutover.** 5.9.x does not read the old `SCHEDULER_DATA_PARTITIONING_*` keys or the old flat archiving variables. Settings left under the old names are silently ignored, falling back to defaults.
</Warning>

***

## Configuration: before and after

**5.1.x (old):**

```yaml theme={"system"}
flowx:
  data:
    partitioning:
      enabled: true
      interval: MONTH
      retention-intervals: 3
      detached-partition-compression: OFF
      moved-data-batch-size: 5000
scheduler:
  dataPartitioning:
    enabled: true
    cronExpression: "0 0 1 * * ?"
```

**5.9.x (new):**

```yaml theme={"system"}
flowx:
  data:
    partitioning:
      enabled: true
      interval: MONTH
      archiving:
        enabled: true                  # was scheduler.dataPartitioning.enabled
        cronExpression: "0 0 1 * * ?"   # was scheduler.dataPartitioning.cronExpression
        retention-intervals: 3          # moved under archiving
        detached-partition-compression: OFF   # moved under archiving (Oracle only)
        moved-data-batch-size: 5000           # moved under archiving (PostgreSQL only)
```

***

## Environment variable mapping

| 5.1.x variable                                           | 5.9.x variable                                                   |
| -------------------------------------------------------- | ---------------------------------------------------------------- |
| `FLOWX_DATA_PARTITIONING_ENABLED`                        | `FLOWX_DATA_PARTITIONING_ENABLED` (unchanged)                    |
| `FLOWX_DATA_PARTITIONING_INTERVAL`                       | `FLOWX_DATA_PARTITIONING_INTERVAL` (unchanged)                   |
| `SCHEDULER_DATA_PARTITIONING_ENABLED`                    | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`                      |
| `SCHEDULER_DATA_PARTITIONING_CRON_EXPRESSION`            | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`               |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS`            | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`           |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHEDPARTITIONCOMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE`          | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVEDDATABATCHSIZE`           |

***

## Default behavior change

<Warning>
  The archiving scheduler now defaults to **off**. In 5.1.x the scheduler defaulted to on (`SCHEDULER_DATA_PARTITIONING_ENABLED=true`); in 5.9.x `archiving.enabled` defaults to `false`. If you relied on the old default to run archiving, you must explicitly set `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true` after the upgrade, or partitions will accumulate without being archived.
</Warning>

***

## Migration steps

<Steps>
  <Step title="Move archiving settings under the archiving block">
    Rename your retention, compression, and batch-size settings to the `FLOWX_DATA_PARTITIONING_ARCHIVING_*` form shown in the mapping table.
  </Step>

  <Step title="Replace the standalone scheduler variables">
    Drop `SCHEDULER_DATA_PARTITIONING_ENABLED` and `SCHEDULER_DATA_PARTITIONING_CRON_EXPRESSION`. Set `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true` and `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` in their place.
  </Step>

  <Step title="Re-enable archiving explicitly">
    Because the scheduler now defaults to off, confirm `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true` is set if you want archiving to run.
  </Step>

  <Step title="Redeploy and verify">
    Redeploy process-engine and confirm the archiving cron job runs on schedule. Check the `DATA_PARTITIONING_LOG` table for new archiving entries.
  </Step>
</Steps>

***

## Integration Designer

5.9.x also adds partitioning and archiving for **workflow instances** in Integration Designer, using the same `flowx.data.partitioning` structure. It is opt-in and defaults to off, so it is not a required migration step — enable it only if you want to partition workflow instance data. Note that the Integration Designer block does not include the Oracle compression or PostgreSQL batch-size settings.

***

## Rollback

This change is configuration-only. The database schema is forward-compatible — reverting the configuration back to the old block names restores the previous behavior without a schema change.

***

## Related resources

<CardGroup>
  <Card title="Partitioning & archiving setup" icon="table-cells" href="/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving">
    Full partitioning and archiving configuration reference.
  </Card>

  <Card title="Prerequisites & upgrade path" icon="list-check" href="./prerequisites">
    Inventory to gather before the upgrade, including your current partitioning config.
  </Card>
</CardGroup>


# Ingress routing and CORS
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ingress-routing

NGINX ingress controller no longer assumed, CORS handling moved to the application layer, and the optional Gateway API HTTPRoute migration path.

5.1.x deployments route external traffic through Kubernetes Ingress resources rendered by the FlowX Helm chart, with NGINX as the assumed ingress controller. CORS is handled at the ingress layer through `nginx.ingress.kubernetes.io/cors-*` annotations on every per-service Ingress. 5.9.x changes both: the chart no longer assumes ingress-nginx as the bundled controller, and CORS handling moves to the application layer via an environment variable on each backend service.

The chart on 5.9.x ships Kubernetes Ingress and Gateway API HTTPRoute templates side-by-side; each service can be toggled independently between the two modes. The Service Route Reference and full configuration are documented in the [ingress configuration guide](/5.9/setup-guides/ingress-configuration).

<Info>
  This migration is operated by FlowX during the 5.1.x → 5.9.x upgrade window for self-hosted deployments. The customer-facing actions are limited to verifying CORS origins and confirming the post-upgrade ingress controller choice with your FlowX representative.
</Info>

***

## CORS handling moves into the services

On 5.9.x, CORS is handled inside each backend service's code rather than at the ingress layer. Each service's `application.yaml` ships with sensible defaults for allowed methods, headers, and credentials. Only the **allowed origins** list is deployment-specific and must be configured per environment.

The change applies to every backend service that is exposed through an admin or public URL: `admin`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway`. Internal-only services do not serve browser traffic and are unaffected.

### Set `APPLICATION_CORS_ALLOWORIGIN` per deployment

`APPLICATION_CORS_ALLOWORIGIN` accepts a comma-separated list of origins:

```yaml theme={"system"}
env:
  APPLICATION_CORS_ALLOWORIGIN: "https://designer.yourcompany.com,https://*.yourcompany.com"
```

Wildcard subdomain patterns are supported. The list must include every domain that your Designer, runtime renderers, and custom integrations are served from. The variable must be set on each of the 15 services listed above.

<Warning>
  Origins that are not listed in `APPLICATION_CORS_ALLOWORIGIN` will be rejected at the service layer with a CORS error in the browser, even if the request reaches the backend successfully. CORS failures surface only in the browser console. Backend logs show the request as successful.
</Warning>

### Other CORS settings use safe defaults

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`, and the other FlowX-specific headers used by the platform), and credential handling are baked into each service's `application.yaml` with the correct values. The defaults are overridable via environment variables but rarely need to change; consult your FlowX representative if you have a non-standard requirement.

### What is removed

The following NGINX-specific annotations are no longer rendered on the chart's ingress templates and are no longer effective for CORS handling:

* `nginx.ingress.kubernetes.io/enable-cors`
* `nginx.ingress.kubernetes.io/cors-allow-credentials`
* `nginx.ingress.kubernetes.io/cors-allow-headers`
* `nginx.ingress.kubernetes.io/cors-allow-methods`
* `nginx.ingress.kubernetes.io/cors-allow-origin`

Custom overrides that referenced these annotations should be removed during the upgrade. They have no effect on 5.9.x.

***

## NGINX ingress controller is no longer assumed

The chart no longer assumes ingress-nginx as the bundled controller in 5.9.x.

Kubernetes Ingress resources themselves remain fully supported with any compliant controller (Traefik, HAProxy, Istio, F5 Container Ingress Services, cloud-provider controllers, etc.). The change applies to the bundled controller the chart historically assumed. Not to Kubernetes Ingress as a routing mechanism. Deployments that already terminate ingress on a non-NGINX controller are unaffected; only the CORS env var change above applies.

### What this means for your deployment

| Current 5.1.x setup                                                       | 5.9.x action                                                                                                                                        |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| ingress-nginx controller deployed alongside FlowX                         | Plan the controller change with your FlowX representative — another Kubernetes Ingress controller, or opt in to Gateway API HTTPRoutes (see below). |
| Existing non-NGINX ingress controller (Traefik, HAProxy, F5, etc.)        | No controller change required. Confirm the chart's `ingressClassName` is set to your controller.                                                    |
| External reverse proxy in front of Kubernetes (F5, corporate API gateway) | No controller change required. The chart's Ingress resources continue to apply behind your proxy.                                                   |

***

## Optional: Gateway API HTTPRoutes

5.9.x ships Gateway API HTTPRoute templates alongside the existing Ingress templates, as an opt-in alternative for customers who want a controller-agnostic routing model. Kubernetes Ingress remains the default for every service; switching to HTTPRoute mode is coordinated with FlowX during the upgrade window and requires the Gateway API CRDs (`gateway.networking.k8s.io/v1`) plus a compatible controller (Envoy Gateway, Istio, Traefik with Gateway API enabled, etc.) on the cluster.

For details, see the [routing guide](/5.9/setup-guides/ingress-configuration).

<Info>
  HTTPRoute adoption is not required at the 5.1.x → 5.9.x upgrade window. Customers staying on Kubernetes Ingress for the 5.9.x release cycle will continue to be supported on the chart's Ingress templates.
</Info>

***

## Customizing routes

If your 5.1.x deployment carries custom NGINX annotations (body-size tuning, timeouts, sticky sessions, custom rewrites, cert-manager, WAF), share the full set with your FlowX representative before the upgrade window so they can be carried forward. See [Routing → Customizing routes](/5.9/setup-guides/ingress-configuration#customizing-routes) for the Ingress ↔ HTTPRoute mapping of common annotations.

***

## Pre-upgrade audit checklist

Before the upgrade window, walk through the following with your FlowX representative:

<Steps>
  <Step title="Inventory CORS origins">
    List every domain that calls FlowX REST APIs from the browser. Include Designer URLs, custom domains, runtime renderer domains, third-party integration hosts, and any local-development origins that need to remain authorized in production.
  </Step>

  <Step title="Confirm ingress controller">
    Confirm which Kubernetes ingress controller your deployment currently uses. If you are on ingress-nginx, decide with FlowX whether to migrate to another controller, adopt Gateway API HTTPRoutes, or stay on ingress-nginx for the 5.9.x cycle.
  </Step>

  <Step title="Share custom annotations">
    If your 5.1.x deployment carries custom annotations on FlowX Ingress resources (body size, timeouts, affinity, custom rewrite, cert-manager, WAF), share the full set with FlowX. They will be carried forward via the chart values.
  </Step>

  <Step title="Verify upstream proxy settings">
    If you have an external reverse proxy in front of Kubernetes (F5, corporate gateway, cloud LB), confirm that origin-rewriting or header-stripping at that layer does not interfere with the new application-level CORS handling.
  </Step>

  <Step title="Plan post-upgrade verification">
    After the upgrade, validate one request from each origin in `APPLICATION_CORS_ALLOWORIGIN` against each affected service. CORS failures surface only in the browser. Backend logs show successful requests.
  </Step>
</Steps>

***

## Related resources

<CardGroup>
  <Card title="Ingress configuration guide" icon="network-wired" href="/5.9/setup-guides/ingress-configuration">
    Service Route Reference, Gateway API HTTPRoute configuration, and route customization for the 5.9.x baseline.
  </Card>

  <Card title="v5.9.0 deployment guidelines" icon="file-lines" href="/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9">
    Component versions, `APPLICATION_CORS_ALLOWORIGIN` environment variable per service, and self-hosted upgrade guidance.
  </Card>

  <Card title="Prerequisites" icon="list-check" href="./prerequisites">
    Complete the pre-upgrade inventory before working through this page.
  </Card>

  <Card title="Migration overview" icon="arrow-up-right-from-square" href="./overview">
    Return to the consolidated 5.1 LTS → 5.9 LTS migration guide.
  </Card>
</CardGroup>


# iOS SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ios

Migrate the FlowX iOS renderer SDK from 5.1.x LTS to 5.9.x.

## iOS SDK migration guide

5.9 bumps the `FlowXRenderer` pod from the 9.x line to the 10.x line. The host-app surface that changes is small: a new mandatory `organizationId` on `FXConfig`, one breaking signature on the callback-based `startProcess`, one new case on `CustomLoaderType`, and a few additive APIs around UI Flows and process-start callbacks.

### Prerequisites and version range

| Requirement     | 5.1.x    | 5.9.x     |
| --------------- | -------- | --------- |
| `FlowXRenderer` | `~> 9.0` | `~> 10.3` |
| Minimum iOS     | iOS 15   | iOS 15    |
| Swift           | 5.9      | 5.9       |
| Xcode           | 18+      | 26+       |

### Configuration changes

#### New mandatory `FXConfig.organizationId`

5.9 introduces `organizationId` as a mandatory `FXConfig` property. It carries the FlowX-issued organization UUID. The same value used to backfill `organization_id` columns during the backend upgrade (see [License and organization configuration](./organization-deployment)).

```swift v9.x theme={"system"}
FXConfig.sharedInstance.configure { config in
    config.baseURL = myBaseURL
    config.enginePath = "engine"
    config.imageBaseURL = myImageBaseURL
    // ...
}
```

```swift v10.x theme={"system"}
FXConfig.sharedInstance.configure { config in
    config.baseURL = myBaseURL
    config.enginePath = "engine"
    config.imageBaseURL = myImageBaseURL
    config.organizationId = myOrganizationUuid
    // ...
}
```

### Breaking API changes

#### `startProcess` (workspaceId callback variant): completion signature

The `completion` closure of the navigation-agnostic `startProcess(workspaceId:projectId:...)` now receives the started process instance UUID alongside the root view controller.

```swift v9.x theme={"system"}
public func startProcess(workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         completion: ((UIViewController?) -> Void)?,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift v10.x theme={"system"}
public func startProcess(workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         completion: ((UIViewController?, String) -> Void)?,
                         onProcessEnded: (() -> Void)? = nil)
```

Update the closure to accept the second argument. The UUID is an empty string if the process failed to start.

```swift theme={"system"}
FlowX.sharedInstance.startProcess(workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true) { rootViewController, processInstanceUuid in
    // present rootViewController; persist processInstanceUuid if you need to resume later
}
```

The other two `startProcess` variants (`navigationController:` and `tabBarController:`) keep the same shape. They only gain an optional `onProcessStarted` callback, which has a default of `nil` and is non-breaking.

#### `CustomLoaderType`: new `.upload` case

A fourth case is added to the enum returned by `FXDataSource.customLoader(type:)`.

```swift v9.x theme={"system"}
public enum CustomLoaderType {
    case startProcess
    case reloadProcess
    case action(String?)
}
```

```swift v10.x theme={"system"}
public enum CustomLoaderType {
    case startProcess
    case reloadProcess
    case action(String?)
    case upload(String?)
}
```

Exhaustive `switch` statements on `CustomLoaderType` stop compiling until `.upload` is handled. Return `nil` to keep the built-in upload loader, or return a custom view to override it.

```swift theme={"system"}
func customLoader(type: CustomLoaderType) -> AnyView? {
    switch type {
    case .startProcess:        return AnyView(MyStartProcessLoader())
    case .reloadProcess:       return AnyView(MyReloadLoader())
    case .action(let name):    return AnyView(MyActionLoader(actionName: name))
    case .upload(let name):    return AnyView(MyUploadLoader(actionName: name))
    }
}
```

The associated `String?` on `.upload` is the upload action name as configured in the process definition.

### App-side migration steps

<Steps>
  <Step title="Bump the pod">
    In your `Podfile`, point `FlowXRenderer` to the version shipped with 5.9 (see *Release Notes → 5.9 Deployment guidelines → Component versions*) and run `pod install`:

    ```ruby theme={"system"}
    pod 'FlowXRenderer', '~> <version>'  # see Release Notes → 5.9 Deployment guidelines
    ```
  </Step>

  <Step title="Set organizationId in FXConfig">
    In the existing `FXConfig.sharedInstance.configure { ... }` block, set `config.organizationId` to your FlowX-issued organization UUID. Apply this before starting the first FlowX session.
  </Step>

  <Step title="Update startProcess call sites">
    For every call to `FlowX.sharedInstance.startProcess(workspaceId:projectId:...)`, update the trailing `completion` closure to accept `(UIViewController?, String)` instead of `(UIViewController?)`.
  </Step>

  <Step title="Handle the new CustomLoaderType.upload case">
    In each `FXDataSource.customLoader(type:)` implementation, add a branch for `.upload(let actionName)`. Return `nil` to keep the default loader.
  </Step>

  <Step title="Rebuild and run">
    `pod install` then a clean build (`Cmd+Shift+K`, then `Cmd+B`). Resolve any remaining type-mismatch warnings the compiler surfaces around the two changed signatures.
  </Step>
</Steps>

### Verification

<Check>
  Start a process from the host app and confirm the `completion` closure receives a non-empty `processInstanceUuid`. Persist it, kill the app, and resume with `FlowX.sharedInstance.continueExistingProcess(uuid:name:...)`. The previously running task should reopen at the correct screen.
</Check>

<Check>
  Trigger a file upload action on a screen that exposes one. With a custom loader registered, confirm `.upload(actionName)` is hit (e.g. by setting a breakpoint or logging the case). Without a custom loader, confirm the built-in upload spinner appears.
</Check>

## New capabilities

These are additive in 5.9; existing 5.1 integrations keep working without adopting them. See the [iOS SDK reference](/5.9/sdks/ios-renderer) for full signatures and samples.

* **UI Flows**. `FlowX.sharedInstance.startUIFlow(workspaceId:projectId:name:params:isModal:showLoader:completion:)` starts a UI Flow defined in the FlowX Designer. UI Flows run client-side over a data model and do not require a BPMN process instance on the engine.
* **`onProcessStarted` callback**. `startProcess(navigationController:)` and `startProcess(tabBarController:)` accept an optional `onProcessStarted: ((String) -> Void)?` that fires with the new process instance UUID once the engine has accepted the start request.

## Related resources

<CardGroup>
  <Card title="iOS SDK reference" icon="apple" href="/5.9/sdks/ios-renderer">
    iOS renderer SDK documentation
  </Card>

  <Card title="Migration overview" icon="arrow-up-right-from-square" href="./overview">
    Full 5.1.x LTS → 5.9.x upgrade guide
  </Card>
</CardGroup>


# Kafka migration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/kafka

One mandatory new header, new Kafka topics that did not exist in 5.1.x, a topic-ownership move, and the custom-producer audit you must run before upgrading.

5.1.x deployments interact with FlowX over Kafka in two ways: messages produced **by** FlowX services (process start, task events, audit, document operations) and messages produced **into** FlowX by your own integrations. The 5.1 → 5.9 jump introduces one breaking change that affects custom producers, several new topics introduced by new services, and one topic-ownership move that affects Kafka ACLs.

***

## Mandatory `Fx-Organization-Id` header

On 5.9.x, every FlowX Kafka consumer validates the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected immediately and not retried.

This is the single most likely cause of silent breakage post-upgrade for customers who maintain custom Kafka producers (process start, task operations, engine responses, integration callbacks).

### What to set

Set the header value to the Organization UUID provided by FlowX during organization registration. The same value you configure as the `ORGANIZATION_ID` environment variable on every FlowX service. See [Prerequisites](./prerequisites#get-your-organization-uuid).

```java theme={"system"}
producerRecord.headers().add("Fx-Organization-Id",
    "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx".getBytes(StandardCharsets.UTF_8));
```

### Where this applies

| Surface                                | Behavior in 5.9.0                                                                                                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Kafka topics consumed by FlowX         | Header is **mandatory**. Missing → message rejected, not retried.                                                                                                                    |
| Kafka responses sent **back** to FlowX | Preserve all received headers (including `Fx-Organization-Id`) when responding from your connector.                                                                                  |
| REST API endpoints                     | Header is read into security context when present, but **not enforced** in 5.9.0. Enforcement on authenticated REST requests is tracked separately and will land in a later release. |

<Warning>
  Pre-existing 5.1.x integrations that simply forward Kafka messages back to FlowX without copying the headers will break. Audit every custom Kafka producer and connector before the upgrade window.
</Warning>

### Affected consumer surfaces

Validation runs on **every** FlowX Kafka listener. Concretely, custom producers that target the following topic families must add the header:

* Process start (`*.core.trigger.start.process.*`, `*.core.trigger.start-for-event.process.*`)
* Process operations (`*.core.trigger.operation.*`, `*.core.trigger.operations.bulk.*`): task assign/unassign, hold/unhold, terminate, including bulk
* Connector responses (`*.engine.receive.*`)
* Webhook ingestion, document plugin triggers, integration sync topics

***

## New Kafka topics that did not exist in 5.1.x

The 5.1 → 5.9 jump adds new microservices (`organization-manager`, `webhook-gateway`, `license`) and new features (Knowledge Base, Multi-file Upload, UI Flow session variables, Email Trigger). Each brings its own topics. For the complete list with producer/consumer mapping, see the deployment guidelines linked at the bottom of this page.

The high-level groups your platform/SRE team should be aware of:

| Theme                                                                  | Notable topics                                                                                                                                                                         |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization-manager` + Document plugin enhancements                  | `ai.flowx.organization.events.v1`, `ai.flowx.application-version.resources-usages.*`, `ai.flowx.plugin.document.trigger.persist.document.*`, `ai.flowx.build.runtime-data.v1`          |
| `webhook-gateway` + UI Flow session variables                          | `ai.flowx.core.trigger.start-for-event.process.v1`, `ai.flowx.core.trigger.ui-flow.update.v1`, `ai.flowx.plugin.document.trigger.persist.document.session.v1`                          |
| AI Providers UI (LLM config)                                           | `ai.flowx.llm.config.changed.v1`                                                                                                                                                       |
| `license` service + KB internal Kafka path + bulk document persistence | `ai.flowx.license.events.v1`, `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` / `-response.v1`, `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` |

<Info>
  If you manage Kafka topic creation manually (rather than letting FlowX auto-create), pre-create the topics listed in each release's deployment guidelines before deploying the corresponding service versions.
</Info>

***

## New producer on `WorkspaceCreatedEvent`: `organization-manager`

`organization-manager` now publishes `WorkspaceCreatedEvent` as part of the organization-provisioning flow. `authorization-system` continues to publish the event on regular workspace creation, so on 5.9.x the topic has **two producers**, not one.

If you manage Kafka ACLs at the topic level, grant producer access to **both** services:

* `authorization-system`. Publishes on user-driven workspace create (unchanged from 5.1.x).
* `organization-manager`. Publishes during org provisioning (new in 5.9.x).

Consumers of the topic do not change. If you rely on FlowX's default Kafka ACL provisioning (no manual ACL management), no action is required.

***

## Knowledge Base indexer ↔ embedder moves to Kafka

On 5.9.x, the Knowledge Base indexer → embedder path uses a Kafka request/response pair instead of synchronous gRPC:

* `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` (indexer producer, embedder consumer)
* `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` (embedder producer, indexer consumer)

This is internal to FlowX. Your integrations are unaffected. The implication for operators is that the embedder no longer needs to receive gRPC calls from the indexer; both services connect to Kafka for KB indexing traffic.

***

## Custom-producer audit checklist

Before the upgrade window, walk through every Kafka integration that produces into FlowX:

<Steps>
  <Step title="Inventory">
    List every system that publishes to a FlowX Kafka topic. Common sources: backends that start processes by name, task-management automations, connector implementations that respond to engine requests, scheduled jobs that emit events.
  </Step>

  <Step title="Add `Fx-Organization-Id` to producer code">
    For each producer, add the header before sending. The value is your Organization UUID (same as the `ORGANIZATION_ID` env var).
  </Step>

  <Step title="Preserve headers on Kafka responses">
    Connectors that respond to FlowX engine requests must copy **all** received Kafka headers (including `Fx-Organization-Id`, `Fx-Workspace-Id`, `fxContext`, `Fx-AppId`) into the response. The simplest pattern: `originalHeaders.forEach(producerRecord.headers()::add)`.
  </Step>

  <Step title="Verify in staging">
    Run end-to-end with a 5.9.x staging environment before production. The failure mode is non-retryable rejection: messages are dropped, not queued for retry, so the breakage stays silent unless you read the consumer logs.
  </Step>

  <Step title="Update Kafka topic ACLs">
    If you manage ACLs manually, switch the `WorkspaceCreatedEvent` producer ACL from `authorization-system` to `organization-manager`. Pre-create any new topics from the table above that aren't already provisioned.
  </Step>
</Steps>

***

## Related resources

<CardGroup>
  <Card title="Creating a Kafka producer" icon="code" href="/5.9/docs/platform-deep-dive/integrations/creating-a-kafka-producer">
    Full reference for required Kafka headers on the 5.9.x baseline, including the `Fx-Organization-Id`, `Fx-Workspace-Id`, and `jwt` headers.
  </Card>

  <Card title="Finding identifiers and parameters" icon="magnifying-glass" href="/5.9/docs/platform-deep-dive/integrations/finding-identifiers-and-parameters">
    Where to find the Organization UUID, workspace ID, project ID, and other identifiers required in Kafka and REST integrations.
  </Card>

  <Card title="v5.9.0 deployment guidelines" icon="file-lines" href="/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9">
    Component versions, Kafka topic ownership, and env vars for the 5.9.x baseline.
  </Card>

  <Card title="Prerequisites" icon="list-check" href="./prerequisites">
    Get your Organization UUID and complete the pre-upgrade inventory before working through this page.
  </Card>
</CardGroup>


# License and organization configuration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment

ORGANIZATION_ID Liquibase parameter on the 9 services that backfill org_id columns, the license microservice that connects self-hosted deployments to FlowX SaaS, and the env vars that replace the legacy Configure Environment Info UI.

Four configuration areas need attention during the 5.1.x → 5.9.x upgrade: the `ORGANIZATION_ID` Liquibase parameter on services that backfill `organization_id` columns, the new `license` microservice that connects self-hosted deployments to FlowX SaaS, the deployment-time env vars that replace the legacy "Configure Environment Info" UI, and the organization registration step at first launch.

<Warning>
  **Confirm your upgrade plan with FlowX before starting.** Some 5.1.x deployment configurations require a custom migration path that this guide does not cover. Your FlowX representative will validate compatibility and provide any tailored migration scripts ahead of the upgrade window.
</Warning>

***

## `ORGANIZATION_ID`: where it is actually required

`ORGANIZATION_ID` is a Liquibase parameter used to backfill new `organization_id` columns on existing tables. It is NOT a service-wide config. Only the services that ship a Liquibase changeset reading `${organization-id}` consume it.

Set the UUID issued by FlowX (see [Prerequisites](./prerequisites#get-your-organization-uuid)) on these **9 services**:

* `application-manager`
* `authorization-system`
* `cms-core`
* `document-plugin`
* `integration-designer`
* `notification-plugin`
* `organization-manager`
* `process-engine`
* `scheduler-core`

Each of these services refuses to start without `ORGANIZATION_ID` set in a non-SaaS deployment. **Behavior depends on the deployment scenario:**

| Scenario                                  | Is `ORGANIZATION_ID` required?       | What happens                                                                                                                |
| ----------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Upgrade from 5.1.x** (this guide)       | **Required** on the 9 services above | Liquibase backfills `organization_id` on existing rows with your UUID, then enforces `NOT NULL`. Missing → migration fails. |
| **Fresh 5.9.x install** (empty databases) | Not required                         | Each affected Liquibase changeset pre-checks for rows; with no rows to backfill, it skips the value-required step.          |

The remaining services (`admin`, `advancing-controller`, `audit-core`, `data-search`, `data-sync`, `email-gateway`, `events-gateway`, `license`, `nosql-db-runner`, `runtime-manager`, `task-management-plugin`, `webhook-gateway`) do NOT declare `ORGANIZATION_ID` as a Liquibase parameter. Setting it on those is harmless but unnecessary.

<Warning>
  **Do not set `ORGANIZATION_ID` on a SaaS deployment** (`FLOWX_SAAS=true`). The value is intended only for self-hosted upgrades and will conflict with the SaaS provisioning flow if set.
</Warning>

| Environment Variable | Description                                                                              | Default Value        |
| -------------------- | ---------------------------------------------------------------------------------------- | -------------------- |
| `ORGANIZATION_ID`    | Organization UUID issued by FlowX. Liquibase backfill parameter on the 9 services above. | `-` (FlowX-provided) |

***

## The `license` service uses a separate env var

The `license` service does NOT read the Liquibase `ORGANIZATION_ID` parameter. Instead, it consumes `FLOWX_LICENSE_ORGANIZATIONID` at runtime as the OAuth client-id for the FlowX SaaS license handshake.

Both env vars carry the same UUID value, but they bind to different Spring properties on different services. See the next section for the full `license` service env var table.

***

## Liquibase migration

When you boot 5.9.x for the first time against your 5.1.x databases:

* **Active process instances** are migrated automatically. The default organization is replaced with your registered Organization UUID.
* **Inactive and archived process instances** are not migrated automatically. **FlowX provides custom migration scripts on demand**. Request these from your FlowX representative before resuming runtime traffic, otherwise inactive instances will not be visible to users post-upgrade.

Plan the upgrade window with enough margin for Liquibase to complete; large deployments with many active instances will see migration runtime measured in minutes per service.

<Tip>
  **Verify migration completion** by running the data-sync job after services boot. It surfaces any migration that failed silently or was skipped.
</Tip>

<Warning>
  **Run the data-sync job before users log in.** Organizations provisioned on 5.1.x do not have the "All end-users" runtime group — it is created during organization provisioning or by the data-sync job. Until data-sync finishes, every login (including FlowX Designer) fails with an Internal Server Error in `authorization-system`:

  ```
  NullPointerException: ... DefaultRuntimeGroupService.getRuntimeGroupAllEndUsers(java.util.UUID)" is null
  ```

  If a login was attempted before data-sync ran, the failed lookup stays cached in Redis until the cache TTL (`REDIS_TTL`) expires — after data-sync completes, clear the `authorization-system` cache entries (key prefix `flowx:core:cache:authorization-system:`), then log in again.
</Warning>

***

## The `license` microservice

5.9.x ships a `license` service (PostgreSQL + Redis + Kafka + SpiceDB) that connects self-hosted deployments to FlowX SaaS for:

* License validation against the registered Organization UUID.
* Usage reporting (process instances, active users, AI usage counters).
* Receipt of license events (renewal, expiry, plan changes).

Configure the connection. **All four values are provided by FlowX licensing** for the self-hosted deployment; none are derivable from the self-hosted environment:

| Environment Variable           | Description                                                                                                                                                               | Default Value |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_LICENSE_KEY`            | License key issued by FlowX. Required — without it the license service cannot authenticate to FlowX SaaS, and the wizard's token validation step fails.                   | `-`           |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization UUID issued by FlowX. Same value used as the `ORGANIZATION_ID` Liquibase parameter. The default `notset` must be replaced before the license service starts. | `notset`      |
| `FLOWX_LICENSE_AUTHSERVERURL`  | Auth endpoint provided by FlowX licensing.                                                                                                                                | `-`           |
| `FLOWX_LICENSE_SERVERURL`      | License API endpoint provided by FlowX licensing.                                                                                                                         | `-`           |

<Info>
  **The `license` service authenticates against two Keycloak instances.** Inbound authentication uses the self-hosted Keycloak (configured via `SECURITY_OAUTH2_BASE_SERVER_URL` like every other service). Outbound calls to FlowX SaaS use a separate OAuth client, configured via the `FLOWX_LICENSE_*` env vars above.
</Info>

<Warning>
  **Outbound HTTPS to the FlowX-provided license endpoints** must be open from the `license` service. Confirm with your network team before the upgrade. Restricted environments may need an outbound proxy and an allow-list entry for the endpoints supplied with your license key.
</Warning>

***

## Required self-hosted env vars

The legacy environment-info UI is no longer available. Its values move to deployment-time env vars, set on the services below:

| Environment Variable                               | Description                                                                                                                   | Default Value                    | Component            |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------------- |
| `DEFAULT_ORGANIZATION_NAME`                        | Organization code registered with FlowX. Used for Designer routing and display.                                               | `''`                             | designer             |
| `FLOWX_DEFAULT_DESIGNER_HOMEURI`                   | URL of the Designer container app served to this deployment.                                                                  | `-`                              | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOMEURI`                    | URL of the generic runtime container app served to end users.                                                                 | `-`                              | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` | Comma-separated list of redirect URIs allowed on the user realm. If empty, derived from the Designer/Runtime home URIs above. | `[]`                             | organization-manager |
| `SECURITY_OAUTH2_BASE_SERVER_URL`                  | Self-hosted Keycloak base URL.                                                                                                | `-`                              | organization-manager |
| `SECURITY_OAUTH2_PUBLIC_SERVER_URL`                | Public-facing Keycloak URL. Falls back to `SECURITY_OAUTH2_BASE_SERVER_URL` if unset.                                         | `-`                              | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY`                        | Master key used to encrypt AI Provider credentials at rest. **Change from default before production.**                        | `default-dev-key-change-in-prod` | organization-manager |

<Warning>
  **`LLM_ENCRYPTION_MASTER_KEY` must be changed from its default value before going to production.** The default `default-dev-key-change-in-prod` encrypts BYOK LLM provider credentials in the AI Providers UI. Leaving it in place means anyone with read access to the source code or default deployment manifests can decrypt your provider keys.
</Warning>

<Info>
  **Env var naming convention.** Spring relaxed binding accepts both the canonical UPPER\_SNAKE form (`FLOWX_DEFAULT_DESIGNER_HOMEURI`) and the squished form (`FLOWX_DEFAULT_DESIGNER_HOMEURI`). Examples in this guide use the canonical form to match the k8s base templates; if you copy env vars from an older Helm chart and see the squished form, both bind to the same property.
</Info>

In addition, the `authorization-system` service requires master-realm admin credentials and service-account secrets. See [Authentication & IAM migration](./authentication-iam) for the full list.

***

## Creating the self-hosted organization

FlowX licensing provisions the organization and license for your deployment. After the platform is deployed, the Designer's first-time **Environment Setup** wizard captures the environment name and organization-admin credentials, then completes provisioning automatically.

<Frame>
  ![Environment Setup wizard with environment name and organization admin details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/env_setup.png)
</Frame>

For environments where FlowX drives the installation, your FlowX representative leads this step. Self-installing operators receive the required values directly from FlowX licensing.

<Warning>
  **Outbound HTTPS connectivity to FlowX SaaS is required during provisioning.** The wizard validates the license token and retrieves the subscription via the FlowX-provided endpoints. Without that connectivity the organization row is created and Keycloak realms are provisioned, but license validation fails. Restricted or air-gapped deployments must coordinate an offline-licensing path with FlowX before provisioning.
</Warning>

<Tip>
  **Manual Keycloak alternative.** If your environment does not allow the self-hosted platform to administer Keycloak (no master-realm admin available), follow the [Manual Keycloak Configuration recipe](/5.9/setup-guides/access-management/configuring-an-iam-solution) instead of the wizard. Realms, clients, and roles are then created manually in Keycloak; the platform reads them on first boot.
</Tip>

***

## Deprecated: "Configure Environment Info"

The Configure Environment Info UI in Designer is no longer available. Environment naming now happens during organization registration with FlowX.

The legacy env vars are deprecated and still read for backward compatibility. Plan to remove them once organization registration is complete:

| Environment Variable     | Replaced by                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `FLOWX_CLIENT_NAME`      | Registered organization code (`DEFAULT_ORGANIZATION_NAME`)       |
| `FLOWX_ENVIRONMENT_NAME` | Captured during organization registration; no env var equivalent |

The following API surface is changed; update any custom client tooling that relied on it:

* **`PATCH /api/platform/environment`**. Endpoint removed.
* **`/api/init` response**. The `environmentDetails` section is deprecated; values now come from organization registration rather than the legacy env vars. The field continues to be returned during the upgrade window.

***

## Verify the configuration

After services boot on 5.9.x, confirm:

<Check>
  Every service shows the new Organization UUID in its startup logs (search for `ORGANIZATION_ID` log lines).
</Check>

<Check>
  **Designer → Platform Status** shows all components at their 5.9.x target versions.
</Check>

<Check>
  Liquibase migrations completed on every service. No service is in a "migration pending" state.
</Check>

<Check>
  The `license` service is reachable from your network to FlowX SaaS. License validation succeeds and usage events are being published.
</Check>

<Check>
  `LLM_ENCRYPTION_MASTER_KEY` is set to a non-default value before any LLM provider is configured.
</Check>

***

## Related resources

<CardGroup>
  <Card title="v5.9.0 deployment guidelines" icon="server" href="/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9">
    Component versions, third-party dependency versions, and the complete env var diff.
  </Card>

  <Card title="License engine setup" icon="key" href="/5.9/setup-guides/license-engine-setup">
    Full license service setup including PostgreSQL, Redis, and Kafka topology.
  </Card>

  <Card title="Organization manager setup" icon="building" href="/5.9/setup-guides/organization-manager-setup">
    Deeper reference for organization-manager configuration.
  </Card>

  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Prerequisite. The Keycloak transition that supports this configuration.
  </Card>
</CardGroup>


# Migrating from 5.1 LTS
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/overview

Plan and execute a direct upgrade from FlowX.AI 5.1.x LTS to 5.9.x LTS.

This guide consolidates every breaking change, new service, and required configuration accumulated since the 5.1.x LTS line into the single supported self-hosted upgrade path: **5.1.x → 5.9.x LTS**.

<Info>
  **5.9.0 is the first release in the 5.9.x LTS family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Direct upgrade from 5.1.x LTS to 5.9.0 is the supported self-hosted path.
</Info>

## What changes at a glance

<Frame>
  ![FlowX.AI 5.1.x LTS → 5.9.0 LTS architecture delta](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/flowx-5.1-to-5.9-delta.svg)
</Frame>

The diagram above summarizes the upgrade scope: four new backend microservices, an AI Platform reorganization (deprecated services dropped, new services added, the lineup consolidated to 10), a new React Native client SDK, and a new client-provisioned vector database (Qdrant). The sections below cover each area in detail.

### New services since 5.1.x LTS

5.9.0 introduces 13 microservices that did not exist in 5.1.x.

**Backend microservices (4):**

* `email-gateway`. Outbound email delivery
* `organization-manager`. Organization, workspace, and LLM configuration (absorbs the deprecated `ai-platform-models` service)
* `webhook-gateway`. Inbound webhook intake
* `license`. License verification

**AI Platform services (4):**

* `ai-platform-ai-assistant`. Replaces the 5.1.x `ai-assistant` service
* `embedder`. Embedding generation
* `knowledgebase-rag`. Retrieval-augmented generation backend
* `knowledgebase-indexer-v2`. Knowledge base indexing pipeline

**Standalone AI services (5)**. Separate repositories under `flowx-ai/`, installed independently from the AI Platform umbrella chart:

* `doc-parser`
* `doc-converter`
* `web-crawler`
* `data-privacy` (PII Guard)
* `modpod`

**Deprecated in 5.9.0 (9 AI Platform services):** `ai-assistant`, `ai-platform-connected-graph`, `ai-platform-knowledge-graph`, `ai-platform-agents`, `ai-platform-conversations`, `ai-platform-tenants`, `ai-platform-binaries`, `mcp`, `ai-platform-models`. Plan their removal from your deployment manifests during the upgrade.

### Supported upgrade paths

| Source version               | Path                | Notes                                                                                         |
| ---------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| **5.1.x LTS**                | Supported           | Direct upgrade from 5.1.x to 5.9.x is supported. The sections below cover the full migration. |
| Any other self-hosted source | FlowX-assisted only | Custom migration plan required. Contact your FlowX representative.                            |

<Note>
  **Phased upgrades:** if you upgrade lower environments (dev, test) to 5.9.x while upper environments (staging, production) stay on 5.1.x for a while, you can still ship fixes to the not-yet-upgraded environments. See [Cross-version export and import](../docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
</Note>

***

## How this guide is organized

Each section below is a self-contained topic. Read them in the order shown for a first-time upgrade; experienced operators can jump directly to the topics that affect them.

<CardGroup>
  <Card title="Prerequisites & upgrade path" icon="list-check" href="./prerequisites">
    Audience, supported source versions, inventory you should gather before starting, and what FlowX assists with.
  </Card>

  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Keycloak two-realm architecture, service-account client renames, opaque-token removal, SMTP configuration. The largest single break.
  </Card>

  <Card title="Runtime authorization migration" icon="users-gear" href="./runtime-authorization">
    Org-level roles become project-version-scoped. End-user groups move from Keycloak into FlowX. Per-environment sharing.
  </Card>

  <Card title="Organization & deployment configuration" icon="building-shield" href="./organization-deployment">
    Single-org default mode, the `ORGANIZATION_ID` Liquibase parameter on 5 services, the new `license` microservice, and the env-info deprecation.
  </Card>

  <Card title="Kafka migration" icon="message" href="./kafka">
    Mandatory `Fx-Organization-Id` header for every custom producer, new Kafka topics that did not exist in 5.1.x, and one topic-ownership move.
  </Card>

  <Card title="Ingress routing and CORS" icon="network-wired" href="./ingress-routing">
    NGINX ingress controller deprecation, CORS handling moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable, and the optional Gateway API HTTPRoute path.
  </Card>

  <Card title="API & integration breaking changes" icon="code" href="./api-breaking-changes">
    Endpoint rename (`get-input-json` → `get-start-metadata`), `PATCH /api/platform/environment` removed, `Fx-Organization-Id` header mandatory, and opaque-token removal.
  </Card>

  <Card title="Engine partitioning configuration" icon="table-cells" href="./engine-partitioning">
    The partitioning config consolidated under `flowx.data.partitioning.archiving`; the standalone `SCHEDULER_DATA_PARTITIONING_*` variables are gone and the archiving scheduler now defaults to off.
  </Card>
</CardGroup>

### Renderer SDK migration

<CardGroup>
  <Card title="Android SDK" icon="android" href="./android">
    Migrate the Android renderer from 5.1.x (9.0.x) to 5.9.x (10.x).
  </Card>

  <Card title="iOS SDK" icon="apple" href="./ios">
    Migrate the iOS renderer from 5.1.x to 5.9.x.
  </Card>

  <Card title="React SDK" icon="react" href="./react">
    Migrate the React renderer from 5.1.x to 5.9.x (includes React 19 upgrade).
  </Card>

  <Card title="Angular SDK" icon="angular" href="./angular">
    Migrate the Angular renderer from 5.1.x to 5.9.x.
  </Card>
</CardGroup>

***

## What this guide assumes

* You are upgrading a **self-hosted 5.1.x LTS deployment**.
* You have agreed the upgrade plan with FlowX in advance. Some 5.1.x deployments may need a custom migration path that this guide does not cover; your FlowX representative will confirm the path before you start.
* You have engaged FlowX for the **Liquibase migration of inactive/archived process instances**. Active instances are migrated automatically; inactive ones require FlowX assistance.

If any of these are not true, contact your FlowX representative before starting. Your path may differ from the one described here.


# Prerequisites & upgrade path
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/prerequisites

Audience, supported source versions, and the inventory you should gather before starting the 5.1 LTS → 5.9 LTS upgrade.

## Audience and scope

This guide is for **operators of self-hosted FlowX.AI 5.1.x LTS deployments** upgrading to **5.9.x LTS**. The 5.9.x LTS family opens with **5.9.0** (target 2026-06-02) and continues with monthly LTS patches from July 2026 onward.

* **In scope:** Self-hosted deployments running any 5.1.x patch level.
* **Out of scope:** SaaS deployments. They are continuously upgraded on the SaaS line and do not perform this migration. Any other self-hosted source version requires a FlowX-assisted custom migration plan.

The upgrade jumps directly from the 5.1.x LTS line to the 5.9.x LTS line.

<Warning>
  **Confirm your upgrade plan with FlowX before starting.** Some 5.1.x deployment configurations require a custom migration path that this guide does not cover. Your FlowX representative will validate compatibility and provide any tailored migration scripts ahead of the upgrade window.
</Warning>

***

## Get your Organization UUID

FlowX issues an Organization UUID when your organization registers with FlowX SaaS for license validation and usage reporting. Request it from your FlowX representative before the upgrade window starts.

You will need this single UUID for:

* The `ORGANIZATION_ID` Liquibase parameter on 9 services (`application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`). See [Organization & deployment configuration](./organization-deployment#organization_id--where-it-is-actually-required) for the full behavior.
* The `FLOWX_LICENSE_ORGANIZATIONID` runtime env var on the `license` service (OAuth client-id for the FlowX SaaS license handshake. Different env var, same UUID value).
* The `Fx-Organization-Id` Kafka header on every custom producer.

***

## Inventory to gather

Before the upgrade window, capture the following from your current 5.1.x deployment:

<Steps>
  <Step title="Current component versions">
    Open **FlowX.AI Designer → Platform Status** and record the version of each FlowX component. You will compare these against the 5.9.x targets in the [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) after the upgrade.
  </Step>

  <Step title="Current SDK versions">
    List the `@flowx/*` web SDK package versions in each container app, plus the iOS and Android renderer versions. iOS and Android renderers ship on the 9.0.x line in 5.1.x; 5.9.x targets the 10.x line. Web `@flowx/*` packages follow the Designer version baseline, not the renderer 9/10 numbering.
  </Step>

  <Step title="Keycloak realms and clients">
    Export the list of realms, clients, client scopes, and protocol mappers from your current Keycloak. 5.9.x introduces a dedicated service-accounts realm and renames every service-account client to a `flowx-{service}-sa` pattern. See [Authentication & IAM migration](./authentication-iam).
  </Step>

  <Step title="Kafka topic ACLs and custom producers">
    If you manage Kafka topic ACLs manually, list every topic and its producers/consumers. The `WorkspaceCreatedEvent` topic ownership changes on 5.9.x. List every custom Kafka producer your team operates. Each must add the `Fx-Organization-Id` header on 5.9.x.
  </Step>

  <Step title="Custom API clients">
    Identify any internal tooling that calls:

    * `GET /api/process-definition/{uuid}/get-input-json`. Renamed to `/get-start-metadata` on 5.9.x.
    * `PATCH /api/platform/environment`. Removed on 5.9.x.
    * Any client that reads `environmentDetails` from `/api/init`. Field is deprecated on 5.9.x; its values now come from organization registration rather than the legacy `FLOWX_CLIENT_NAME` / `FLOWX_ENVIRONMENT_NAME` env vars. Migrate clients off this field.
  </Step>

  <Step title="Partitioning configuration">
    If you enabled data partitioning on 5.1.x, capture the current `scheduler.dataPartitioning` YAML block and the five related env vars. The structure and names change on 5.9.x; your FlowX representative will share the new YAML during the upgrade plan.
  </Step>

  <Step title="Backups">
    Take fresh backups of:

    * All Postgres databases (per-service).
    * All MongoDB databases (per-service).
    * Keycloak realm exports.
    * SpiceDB schema and relations.

    Rollback paths after the 5.9.x schema migrations (organization-manager, runtime authorization tables) require restore from backup. See [Rollback considerations](#rollback-considerations) below.
  </Step>
</Steps>

<Warning>
  **Carry forward every required configuration from your 5.1.x deployment.** This guide documents what *changes* on 5.9.x; it does not re-list every configuration value your services already require. Values your 5.1.x services depend on — such as SpiceDB connection and credentials, Redis, and database settings — remain required on 5.9.x and must be carried over. If a service fails to start and its logs report a missing configuration, that value is required: take it from your existing 5.1.x configuration.
</Warning>

***

## Dropped third-party dependency versions

The following third-party versions are no longer supported in 5.9.0. Upgrade them before the FlowX 5.9 upgrade window — running an unsupported version after the FlowX upgrade is not covered by the standard support process.

| Dependency | Dropped versions        | Minimum supported in 5.9.0 |
| ---------- | ----------------------- | -------------------------- |
| Kafka      | 3.8 and older           | 3.9                        |
| Redis      | Versions older than 8.2 | 8.2                        |

<Note>
  Versions are dropped from the supported list as upstream support is no longer provided. For the full supported-version matrix (Keycloak, PostgreSQL, MongoDB, Oracle, Elasticsearch Sink Connector, renderer SDKs), see the [v5.9.0 deployment guidelines — Third-party recommended component versions](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#third-party-recommended-component-versions).
</Note>

***

## Infrastructure deltas

The 5.1 → 5.9 jump adds several runtime dependencies your 5.1.x environment may not already have:

| Dependency                                                 | Used by                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Qdrant**                                                 | Knowledge Base infrastructure (vector storage)                                                                                                                                                                                                                 |
| **SpiceDB**                                                | Expanded coverage on 5.9.x — `data-search` and `email-gateway` join the existing SpiceDB consumers                                                                                                                                                             |
| **Kafka Connect (Strimzi) + Elasticsearch Sink Connector** | Process-engine indexing into Elasticsearch via Kafka. Required only if you enable `FLOWX_INDEXING_TYPE=kafka`. See [Configuring Elasticsearch indexing](/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing). |
| **Outbound HTTPS to FlowX SaaS**                           | `license` service (license validation, usage reporting)                                                                                                                                                                                                        |
| **SMTP server**                                            | Keycloak (password reset, user invitations)                                                                                                                                                                                                                    |

### New services to deploy

5.9.x ships several microservices that do not exist in a 5.1.x deployment. Ensure Helm charts and infrastructure are provisioned for these before upgrading:

| Service                  | Purpose                                                                                                                                | Setup guide                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **webhook-gateway**      | Receives incoming HTTP webhooks from external systems and routes them to processes via Kafka                                           | [Webhook Gateway setup](/5.9/setup-guides/webhook-gateway-setup)           |
| **email-gateway**        | IMAP/Outlook email trigger and sender for processes and workflows                                                                      | [Email Gateway setup](/5.9/setup-guides/email-gateway-setup)               |
| **file-gateway**         | Ingests files from FTP/SFTP/S3/Azure Blob and delivers generated files back; can trigger processes when new files arrive               | [File Gateway setup](/5.9/setup-guides/file-gateway-setup)                 |
| **ai-gateway**           | Powers the AI chat experience in FlowX Designer, streaming AI assistant responses to the browser and routing requests to the AI agents | [AI Gateway setup](/5.9/setup-guides/ai-gateway-setup)                     |
| **license**              | License validation and usage reporting (requires outbound HTTPS to FlowX SaaS)                                                         | [License setup](/5.9/setup-guides/license-engine-setup)                    |
| **organization-manager** | Organization and multi-tenancy management                                                                                              | [Organization Manager setup](/5.9/setup-guides/organization-manager-setup) |
| **authorization-system** | Fine-grained authorization via SpiceDB                                                                                                 | [Authorization System setup](/5.9/setup-guides/authorization-setup-guide)  |

<Info>
  The **AI Platform** is also new on 5.9.x. If your deployment uses AI features, refer to the [AI Platform setup](/5.9/ai-platform/ai-platform-setup) guide for the full list of AI services (agent-builder, knowledgebase-rag, embedder, and others) and their infrastructure requirements (Qdrant and S3).

  The AI Platform also ships a versioned documentation image (`flowx-docs:5.9.0`) that is mounted into the **AI Assistant** so it can answer from the FlowX documentation. It is a content image, not a standalone service; pull the version matching your release (see the component versions in the deployment guidelines).
</Info>

Confirm minimum versions against the [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) Third-party recommended component versions table before scheduling the upgrade window.

***

## Rollback considerations

Not every change in the 5.1 → 5.9 upgrade is reversible by configuration alone.

* **Partitioning configuration rename**. Configuration-only. Reverting the new `partitioning.archiving` block back to `scheduler.dataPartitioning` restores the previous behavior; the database schema is forward-compatible.
* **`organization-manager` service**. Adds new PostgreSQL schemas. Rollback requires database backup restore.
* **Keycloak two-realm transition**. Service-account clients and realm structure change. Rollback requires restoring Keycloak from realm export and reverting the service-account client IDs.
* **Runtime authorization**. End-user groups move from Keycloak to FlowX. Sharing assignments are FlowX-side records that have no Keycloak equivalent to roll back to.

Plan the upgrade window with the assumption that rolling back to 5.1.x requires a full backup restore. Confirm restoration procedures during pre-upgrade rehearsal.

***

## Next

<CardGroup>
  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Start with this. It is the largest single break.
  </Card>

  <Card title="Runtime authorization migration" icon="users-gear" href="./runtime-authorization">
    Project-scoped roles, end-user groups, per-environment sharing.
  </Card>
</CardGroup>


# React SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/react

Migrate the FlowX React renderer SDK from 5.1.x LTS to 5.9.x.

## React SDK migration guide

5.9 bumps the React renderer to React 19, Node 24, and npm 11. Custom validators move to a Valtio-based layer, and the SDK exposes new top-level props (`cache`, interceptors, `onProcessEnded`, `buildId`).

### Framework upgrade: React 18 → 19

The 5.9 React SDK requires React 19 in the host app. Follow the official [React 19 upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide).

| Requirement | 5.1     | 5.9          |
| ----------- | ------- | ------------ |
| React       | \~18    | **19**       |
| Node        | 18.16.9 | **≥ 24.0.0** |
| npm         | v10.8.0 | **≥ 11.0.0** |

<Warning>
  The host app **must** be on React 19 before installing the 5.9 SDK. Mixed-React trees fail at runtime with hook-mismatch errors.
</Warning>

### FlowX SDK changes

#### Organization ID property

We've added a new `organizationId` mandatory prop to the `FlxProcessRenderer` component. See SDK documentation for more details.

```typescript theme={"system"}
<FlxProcessRenderer
  ...
  organizationId={'10000001-0001-0001-8001-100000000001'}
/>
```

#### Custom validators no longer use React Hook Form

In 5.1, validators were piped through React Hook Form. In 5.9 they are processed through a custom Valtio-based validation layer.

The validator function signature is unchanged:

```typescript theme={"system"}
const myValidator = (...params: string[]) => (v: any) => boolean | Promise<boolean>
```

If you relied on React Hook Form internals (e.g. `register`, `setError`, `getValues`) inside a custom validator, refactor to use only the value argument `v`.

### Theming and components

`@flowx/react-sdk` now depends directly on `date-fns@4`. Host apps that pin `date-fns` must move to the 4.x line.

`@flowx/react-ui-toolkit` bumps `air-datepicker` to `3.6.0` and adds `marked` and `sanitize-html` to support markdown rendering in rich-text components.

## Related resources

<CardGroup>
  <Card title="React SDK reference" icon="react" href="/5.9/sdks/react-renderer">
    React renderer SDK documentation
  </Card>

  <Card title="Migration overview" icon="arrow-up-right-from-square" href="./overview">
    Full 5.1.x LTS → 5.9.x upgrade guide
  </Card>
</CardGroup>


# Runtime authorization migration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/runtime-authorization

How runtime roles, end-user groups, and solution sharing change between FlowX.AI 5.1.x and 5.9.x, and what you need to redo per environment after the upgrade.

In 5.1.x, runtime roles were assigned to end users at the organization level and granted access across every project that listed that role. 5.9.x ships a rewritten runtime authorization model: role assignments are **project-version-scoped**, end-user groups move out of Keycloak into FlowX-managed records, and sharing is configured per environment via the Solutions → Share modal.

This page covers the migration concepts. For day-to-day operation of the new model, see the [Runtime authorization setup guide](/5.9/setup-guides/access-management/runtime-authorization).

***

## Mental model: what changed

| Concern                          | 5.1.x                                                 | 5.9.x                                                                                         |
| -------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Where runtime roles are assigned | Directly to users at organization level               | To users **in the context of a project**, via the Solutions → Share modal                     |
| Cross-project effect             | One role grants access on every project that lists it | Role grants access only on the solutions it has been explicitly shared on                     |
| End-user groups                  | Managed in Keycloak                                   | Managed in **FlowX**, assigned to roles on each solution                                      |
| Authentication of end users      | Keycloak                                              | Keycloak (unchanged)                                                                          |
| Authorization decisions          | Keycloak-issued roles consulted at request time       | FlowX-managed runtime authorization service tuned for the volume of runtime permission checks |
| Designer-time permissions        | SpiceDB                                               | SpiceDB (unchanged — separate engine)                                                         |

<Info>
  **Why two engines?** SpiceDB stays as the design-time permission engine for Designer access. Runtime authorization is a separate custom service because the volume of runtime permission evaluations made SpiceDB latency unacceptable. Both coexist and don't interact at runtime.
</Info>

***

## What migrates automatically

The 5.9.x Liquibase migrations handle the bulk of the role + group transition for you:

<Steps>
  <Step title="Existing role-on-user assignments preserved">
    If your 5.1.x users have runtime roles assigned directly, those assignments continue to work after the upgrade. New solutions and new role assignments use the project-scoped model going forward.
  </Step>

  <Step title="Default `User` role on every UI Flow">
    5.9.x gates access per UI Flow with an explicit role allow-list. UI Flows carried over from 5.1.x automatically receive the project-level `User` role on upgrade so existing end users do not lose access. **Review and tighten** the role list per UI Flow as part of the post-upgrade pass.
  </Step>

  <Step title="End-user groups created in FlowX">
    End-user groups previously held in Keycloak are migrated into FlowX-managed records (org-level, named buckets of users). Confirm the migrated group list under **Organization Settings → Access Management → End-User Groups** after the upgrade and adjust as needed.
  </Step>
</Steps>

***

## What does not migrate (and must be redone per environment)

<Warning>
  **Sharing assignments do not export between environments.** This is intentional. When you promote a project build from one environment to another (dev → uat → prod), the Solutions → Share modal assignments are **not** carried over. Re-configure sharing per environment as part of every deployment.
</Warning>

Plan your post-upgrade pass, and every future promotion, around:

* Pick the **Active Policy** for each project. The Share modal only lists roles available in the build set as Active Policy.
* Re-create end-user group assignments per environment.
* Re-issue invitations through Keycloak SMTP for new end users that were created in FlowX as part of the migration.

***

## UI Flow permissions

5.9.x adds an allow-list of roles on every UI Flow. After the upgrade:

<Steps>
  <Step title="Audit the default assignment">
    Every UI Flow carried over from 5.1.x now lists the project-level `User` role. This preserves access for existing end users but is broader than most production deployments want.
  </Step>

  <Step title="Tighten per UI Flow">
    Open each UI Flow in the Designer and reduce the role list to the minimum that needs interactive access. Components inside UI Flows can also be hidden or disabled per role. Use this for finer-grained restrictions inside flows that several roles can still launch.
  </Step>

  <Step title="Test as each role">
    Create a test end-user assigned to a single role, sign in, and verify the UI Flow allow-list and component-level visibility behave as expected.
  </Step>
</Steps>

***

## Designer-user bypass

A user with **Designer access to a project** can run that project at runtime without being assigned a runtime role on it.

* Auto-grants view, execute, and self-assign on every swimlane in the project.
* Lets a project's designers test their own work without being filed into the runtime role catalog.
* Designer users **cannot** test scenarios "as another runtime role." To verify role-specific behavior, create a test end-user, assign the role through the Share modal, and sign in as that user.

The bypass is implemented through a `designerUser` Keycloak user attribute (boolean) auto-managed at organization provisioning. If your environment uses a federated IDP for designer accounts, you may need to add this attribute via an IDP mapper. See [Configuring an IAM solution → Designer user attribute](/5.9/setup-guides/access-management/configuring-an-iam-solution#designer-user-attribute).

***

## What stays in Keycloak vs FlowX

| Concern                                                                                                         | System of record |
| --------------------------------------------------------------------------------------------------------------- | ---------------- |
| Authentication, password policy, MFA                                                                            | Keycloak         |
| User attributes used by [business filters](/5.9/docs/platform-deep-dive/user-roles-management/business-filters) | Keycloak         |
| Federation with external IDPs                                                                                   | Keycloak         |
| Runtime role catalog                                                                                            | FlowX            |
| End-user groups                                                                                                 | FlowX            |
| Project-scoped role assignment (sharing)                                                                        | FlowX            |

***

## Active policy: convert role overrides to group overrides

5.9.0 removes the **Role** override type from active policy. Existing role overrides survive the upgrade visually — they appear in the overrides table with a **DEPRECATED** marker — but they are excluded from runtime resolution. If your 5.1.x setup relied on role overrides to serve a specific build or branch to a subset of end users, redo that targeting with group overrides before promoting the upgrade to production.

<Steps>
  <Step title="List the role overrides you had in 5.1.x">
    For each project, open **Runtime Settings → Active Policy** and note the role, policy type (Latest on Branch or Build), branch/build, and priority of every role override you relied on.
  </Step>

  <Step title="Identify the matching runtime group">
    In 5.9.x, end-user access is configured via runtime groups in the Solutions → Share modal. For each former role override, identify the runtime group whose members should receive the same build or branch. Where you previously targeted a role used by multiple groups, decide whether one group override is enough or whether you need a per-group entry.
  </Step>

  <Step title="Create the group overrides">
    In **Runtime Settings → Active Policy**, click **Add**, choose **Group**, pick the runtime group, set the policy and branch/build, and assign a unique priority. Priority is mandatory for group overrides and decides which one wins when a user belongs to several matching groups. Username overrides always take precedence over group overrides.
  </Step>

  <Step title="Delete the deprecated role overrides">
    Once the equivalent group overrides are in place, delete each deprecated role override row from the table. They have no runtime effect, but removing them keeps the overrides table clean and avoids confusion during audits.
  </Step>
</Steps>

<Tip>
  Repeat this conversion per environment. Like sharing assignments, active policy overrides are not exported with the build and must be reconfigured on each environment the project is promoted to.
</Tip>

***

## Post-upgrade checklist

<Check>
  End-user groups visible under **Organization Settings → Access Management → End-User Groups** match the groups you had in Keycloak.
</Check>

<Check>
  Every UI Flow's role allow-list reviewed and tightened from the default `User` assignment.
</Check>

<Check>
  For each project, the **Active Policy** build is the one you want sharing assigned against.
</Check>

<Check>
  Active policy role overrides from 5.1.x replaced with equivalent group overrides; deprecated role rows deleted.
</Check>

<Check>
  Sharing assignments rebuilt per environment. Confirm at least one end user can access each solution as expected.
</Check>

***

## Related resources

<CardGroup>
  <Card title="Runtime authorization setup guide" icon="shield-halved" href="/5.9/setup-guides/access-management/runtime-authorization">
    Project-scoped roles, the Share modal, end-user groups, and IDP federation in day-to-day operation.
  </Card>

  <Card title="End-user access management" icon="user-group" href="/5.9/setup-guides/access-management/end-user-access-management">
    Org-level end-user, role, and group management.
  </Card>

  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Previous step. The Keycloak transition this rewrite depends on.
  </Card>

  <Card title="License and organization configuration" icon="building-shield" href="./organization-deployment">
    Next step. `ORGANIZATION_ID` Liquibase parameter, the new `license` service, and the env vars that replace the legacy Configure Environment Info UI.
  </Card>
</CardGroup>


# Android SDK
Source: https://docs.flowx.ai/5.9/sdks/android-renderer

Install and configure the FlowX.AI Android SDK to render process-driven UI in native Android apps. Requires Android 8.0+ (API 26).

## Android project requirements

System requirements:

* **minSdk = 26** (Android 8.0)
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

## Installing the library

1. Add the maven repository in your project's `settings.gradle.kts` file:

```kotlin theme={"system"}
dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url = uri("https://nexus-jx.dev.rd.flowx.ai/repository/flowx-maven-releases/")
            credentials {
                username = "your_username"
                password = "your_password"
            }
        }
    }
}
```

2. Add the library as a dependency in your `app/build.gradle.kts` file:

```kotlin theme={"system"}
dependencies {
    ...
    implementation("ai.flowx.android:sdk:<version>")
    ...
}
```

<Info>
  Replace `<version>` with the correct version corresponding to your platform version.<br />
  To find the right version, navigate to:
  <p>`Release Notes → Choose your platform version → Deployment guidelines → Component versions`</p>
</Info>

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**

### Public API

The SDK library is managed through the `Flowx` singleton instance, which exposes the following methods:

| Name                   | Description                                                                                                        | Definition                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init`                 | Initializes the FlowX SDK. Must be called in your application's `onCreate()`                                       | `fun init(context: Context, config: Config, customComponentsProvider: CustomComponentsProvider? = null, customStepperHeaderProvider: CustomStepperHeaderProvider? = null, customLoaderProvider: CustomLoaderProvider? = null, analyticsCollector: AnalyticsCollector? = null, onNewProcessStarted: NewProcessStartedHandler.Delegate? = null)` |
| `setAccessToken`       | Updates the access token                                                                                           | `fun setAccessToken(accessToken: String?)`                                                                                                                                                                                                                                                                                                     |
| `setupTheme`           | Sets up the theme to be used when rendering a process                                                              | `fun setupTheme(workspaceUuid: String, appearance: ThemeAppearance = ThemeAppearance.LIGHT, themeUuid: String, fallbackThemeJsonFileAssetsPath: String? = null, @MainThread onCompletion: () -> Unit)`                                                                                                                                         |
| `changeLocaleSettings` | Changes the current locale settings (i.e. locale and language)                                                     | `fun changeLocaleSettings(locale: Locale, language: String)`                                                                                                                                                                                                                                                                                   |
| `startProcess`         | Starts a FlowX process instance, by returning a `@Composable` function where the process is rendered.              | `fun startProcess(workspaceId: String, projectId: String, processName: String, params: JSONObject? = null, isModal: Boolean = false, onProcessStarted: ((String) -> Unit)? = null, onProcessEnded: (() -> Unit)? = null, closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null): @Composable () -> Unit`              |
| `continueProcess`      | Continues an existing FlowX process instance, by returning a `@Composable` function where the process is rendered. | `fun continueProcess(processUuid: String, isModal: Boolean = false, onProcessEnded: (() -> Unit)? = null, closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null): @Composable () -> Unit`                                                                                                                             |
| `startUiFlow`          | Starts a FlowX UI Flow, by returning a `@Composable` function where the UI Flow is rendered.                       | `fun startUiFlow(workspaceId: String, projectId: String, uiFlowName: String, params: JSONObject? = null): @Composable () -> Unit`                                                                                                                                                                                                              |

## Configuring the library

To configure the SDK, there are two things needed in the project's application class:

1. first, make it implement the `FlowxOwner` interface:

```kotlin theme={"system"}
class MyApplication : Application(), FlowxOwner {
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() }
    // ...
}
```

2. then, call the `init` method inside the `onCreate()` method:

```kotlin theme={"system"}
fun init(
    context: Context,
    config: Config,
    customComponentsProvider: CustomComponentsProvider? = null,
    customStepperHeaderProvider: CustomStepperHeaderProvider? = null,
    customLoaderProvider: CustomLoaderProvider? = null,
    analyticsCollector: AnalyticsCollector? = null,
    onNewProcessStarted: NewProcessStartedHandler.Delegate? = null,
)
```

#### Parameters

| Name                          | Description                                                                                         | Type                                                                   | Requirement                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------- |
| `context`                     | Android application `Context`                                                                       | `Context`                                                              | Mandatory                     |
| `config`                      | SDK configuration parameters                                                                        | `ai.flowx.android.sdk.api.Config`                                      | Mandatory                     |
| `customComponentsProvider`    | Provider for the `@Composable` custom components                                                    | `ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider?` | Optional. Defaults to `null`. |
| `customStepperHeaderProvider` | Provider for the `@Composable` custom stepper header view                                           | `ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider?` | Optional. Defaults to `null`. |
| `customLoaderProvider`        | Provider for the `@Composable` custom loader view                                                   | `ai.flowx.android.sdk.api.custom.loader.CustomLoaderProvider?`         | Optional. Defaults to `null`. |
| `analyticsCollector`          | Collector interface for SDK analytics events                                                        | `ai.flowx.android.sdk.api.analytics.AnalyticsCollector`                | Optional. Defaults to `null`. |
| `onNewProcessStarted`         | Callback for when a new process was started as a consequence for executing a `START_PROJECT` action | `ai.flowx.android.sdk.api.NewProcessStartedHandler.Delegate`           | Optional. Defaults to `null`. |

• The `custom components` implementation is explained in [its own section](#custom-components).<br />
• The implementation for providing a `custom view for the header` of the [Stepper](../docs/building-blocks/process/navigation-areas#stepper) component is detailed in [its own section](#custom-header-view-for-the-stepper-component).<br />
• The implementation for providing a `custom loader` is explained in [its own section](#custom-loaders).<br />
• Collecting analytics events from the SDK is explained in [its own section](#collecting-analytics-events).<br />
• Handling the start of a new process while in a running process is explained in [its own section](#handling-“start-of-a-new-process”).<br />

#### Sample

```kotlin theme={"system"}
class MyApplication : Application(), FlowxOwner {
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() }

    override fun onCreate() {
        super.onCreate()
        initFlowXSdk()
    }

    private fun initFlowXSdk() {
        Flowx.getInstance().init(
            context = applicationContext,
            config = object : Config {
                override val organizationId: String = "organization id"
                override val baseUrl = "URL to FlowX backend",
                override val imageBaseUrl = "URL to FlowX CMS Media Library",
                override val enginePath = "some_path",
                override val language = "en",
                override val locale = Locale.getDefault(),
                override val validators: Map<String, (String) -> Boolean>? = mapOf("exact_25_in_length" to { it.length == 25 }),
                override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE,
            },
            customComponentsProvider = object : CustomComponentsProvider {...},
            customStepperHeaderProvider = object : CustomStepperHeaderProvider {...},
            customLoaderProvider = object : CustomLoaderProvider {...},
            analyticsCollector = { event ->
                // Process / Send the event to some specialized Analytics platform
            },
            onNewProcessStarted = { processInstanceUuid ->
                // Send a broadcast message to notify the Activity currently displaying the running process.
                // The Activity should handle the broadcast to reload and display the newly started process identified by `processInstanceUuid`.
            }
        )
    }
}
```

The configuration properties that should be passed as `Config` data for the `config` parameter above are:

| Name             | Description                                                         | Type                                | Requirement                                 |
| ---------------- | ------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------- |
| `organizationId` | Id of the organization used by FLOWX to identify your installation  | `String`                            | Mandatory                                   |
| `baseUrl`        | URL to connect to the FlowX back-end environment                    | `String`                            | Mandatory                                   |
| `imageBaseUrl`   | URL to connect to the FlowX Media Library module of the CMS         | `String`                            | Mandatory                                   |
| `enginePath`     | URL path segment used to identify the process engine service        | `String`                            | Mandatory                                   |
| `language`       | The language used for retrieving enumerations and substitution tags | `String`                            | Optional. Defaults to `en`.                 |
| `locale`         | The locale used for date, number and currency formatting            | `java.util.Locale`                  | Optional. Defaults to `Locale.getDefault()` |
| `validators`     | Custom validators for form elements                                 | `Map<String, (String) -> Boolean>?` | Optional.                                   |
| `logEnabled`     | Flag indicating if logs should be printed                           | `Boolean`                           | Optional. Defaults to `false`               |

#### Custom validators

The `custom validators` map is a collection of lambda functions, referenced by *name* (i.e. the value of the `key` in this map), each returning a `Boolean` based on the `String` which needs to be validated.
For a custom validator to be evaluated for a form field, its *name* must be specified in the form field process definition.

<Tip>
  By looking at the example from above:

  ```kotlin theme={"system"}
  mapOf("exact_25_in_length" to { it.length == 25 })
  ```

  if a form element should be validated using this lambda function, a custom validator named `"exact_25_in_length"` should be specified in the process definition.
</Tip>

## Using the library

### Authentication

To be able to use the SDK, **authentication is required**. Therefore, before calling any other method on the singleton instance, make sure that the access token is set by calling:

```kotlin theme={"system"}
Flowx.getInstance().setAccessToken(accessToken = "your access token")
```

<Tip>Whenever the access token changes based on your own authentication logic, it must be updated in the renderer by calling the `setAccessToken` method again.</Tip>
<Tip>Passing `null` or empty string (`""`) as an argument to the `setAccessToken` method clears the token</Tip>

### Theming

<Warning>Prior setting up the theme, make sure the `access token` was set.<br />Check the [authentication](#authentication) section for details.</Warning>

To be able to use styled components while rendering a process, the theming mechanism must be invoked by calling the `suspend`-ing `setupTheme(...)` method over the singleton instance of the SDK:

```kotlin theme={"system"}
suspend fun setupTheme(
    workspaceUuid: String,
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: ThemeAppearance = ThemeAppearance.LIGHT,
    @MainThread onCompletion: () -> Unit
)
```

#### Parameters

| Name                              | Description                                                                                                                                                  | Type                    | Requirement                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | -------------------------------------------------- |
| `workspaceUuid`                   | UUID string identifier of the workspace that contains the theme to be loaded                                                                                 | `String`                | Mandatory. Should not be empty                     |
| `themeUuid`                       | UUID string of the theme configured in FlowX Designer                                                                                                        | `String`                | Mandatory. Can be empty                            |
| `fallbackThemeJsonFileAssetsPath` | Android asset relative path to the corresponding JSON file to be used as fallback, in case fetching the theme fails and there is no cached version available | `String?`               | Optional. Defaults to `null`                       |
| `appearance`                      | Indicator for the appearance of the theme (LIGHT, DARK)                                                                                                      | `Flowx.ThemeAppearance` | Options. Defaults to `Flowx.ThemeAppearance.LIGHT` |
| `onCompletion`                    | `@MainThread` invoked closure, called when setting up the theme completes                                                                                    | `() -> Unit`            | Mandatory                                          |

<Note>
  If the `themeUuid` parameter value is empty (`""`), no theme will be fetched, and the mechanism will rely only on the fallback file, if set.<br /><br />
  If the `fallbackThemeJsonFileAssetsPath` parameter value is `null`, there will be no fallback mechanism set in place, meaning if fetching the theme fails, the redered process will have no style applied over it's displayed components.
</Note>

<Note>
  The SDK caches the fetched themes, so if a theme fetch fails, a cached version will be used, if available. Otherwise, it will use the file given as fallback.
</Note>

#### Sample

```kotlin theme={"system"}
viewModelScope.launch {
    Flowx.getInstance().setupTheme(
        workspaceUuid = "some workspace uuid string",
        themeUuid = "some uuid string",
        fallbackThemeJsonFileAssetsPath = "theme/a_fallback_theme.json",
        appearance = Flowx.ThemeAppearance.LIGHT,
    ) {
        // theme setup complete
        // do specific logic
    }
}
```

<Tip>
  The `fallbackThemeJsonFileAssetsPath` always search for files under your project's `assets/` directory, meaning the example parameter value is translated to `file://android_asset/theme/a_fallback_theme.json` before being evaluated.
</Tip>

<Warning>Do not [start](#start-a-flowx-process) or [resume](#resume-a-flowx-process) a process before the completion of the theme setup mechanism.</Warning>

### Changing current locale settings

The current `locale` and `language` can be also changed after the [initial setup](#configuring-the-library), by calling the `changeLocaleSettings` function:

```kotlin theme={"system"}
fun changeLocaleSettings(locale: Locale, language: String)
```

#### Parameters

| Name       | Description                   | Type               | Requirement |
| ---------- | ----------------------------- | ------------------ | ----------- |
| `locale`   | The new locale                | `java.util.Locale` | Mandatory   |
| `language` | The code for the new language | `String`           | Mandatory   |

<Warning>
  **Do not change the locale or the language while a process is rendered.**<br />
  The change is successful only if made before [starting](#start-a-flowx-process) or [resuming](#resume-a-flowx-process) a process.
</Warning>

#### Sample

```kotlin theme={"system"}
Flowx.getInstance().changeLocaleSettings(locale = Locale("en", "US"), language = "en")
```

<Info>
  The `Locale` satisfies the IETF BCP 47 standard for representing language and country/region codes.<br /><br />
  More information regarding the standard can be found by reading [RFC 4647 "Matching of Language Tags"](https://datatracker.ietf.org/doc/html/rfc4647) and [RFC 5646 "Tags for Identifying Languages"](https://datatracker.ietf.org/doc/html/rfc5646).<br /><br />
  An example of BCP 47 is `en-US` (language code `en` and country `US`).
</Info>

### Start a FlowX process

<Warning>Prior starting a process, make sure the [authentication](#authentication) and [theming](#theming) were correctly set up</Warning>

After performing all the above steps and all the prerequisites are fulfilled, a new instance of a FlowX process can be started, by using the `startProcess` function:

```kotlin theme={"system"}
fun startProcess(
    workspaceId: String,
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessStarted: ((String) -> Unit)? = null,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

#### Parameters

| Name               | Description                                                                                        | Type                                                      | Requirement                                         |
| ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------- |
| `workspaceId`      | The id of the workspace that contains the project and process to be started                        | `String`                                                  | Mandatory                                           |
| `projectId`        | The id of the project containing the process to be started                                         | `String`                                                  | Mandatory                                           |
| `processName`      | The name of the process                                                                            | `String`                                                  | Mandatory                                           |
| `params`           | The starting params for the process, if any                                                        | `JSONObject`                                              | Optional. If omitted, if defaults to `JSONObject()` |
| `isModal`          | Flag indicating whether the process can be closed at anytime by tapping the top-right close button | `Boolean`                                                 | Optional. It defaults to `false`.                   |
| \`onProcessStarted | Lambda function where you can do additional processing when the process starts                     | `((String) -> Unit)?`                                     | Optional. It defaults to `null`.                    |
| `onProcessEnded`   | Lambda function where you can do additional processing when the started process ends               | `(() -> Unit)?`                                           | Optional. It defaults to `null`.                    |
| `closeModalFunc`   | Lambda function where you should handle closing the process when `isModal` flag is `true`          | `(CloseModalProcessScope.(processName: String) -> Unit)?` | Optional. It defaults to `null`.                    |

<Tip>
  The returned **[@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable)** function must be included in its own **[Activity](https://developer.android.com/reference/android/app/Activity)**, which is part of (controlled and maintained by) the container application.<br /><br />
  This wrapper activity must display only the `@Composable` returned from the SDK (i.e. it occupies the whole activity screen space).
</Tip>

#### Sample

```kotlin theme={"system"}
class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().startProcess(
                workspaceId = "your workspace id",
                projectId = "your project id",
                processName = "your process name",
                params: JSONObject = JSONObject(),
                isModal = true,
                onProcessStarted = { processInstanceUuid ->
                    // NOTE: possible processing could involve doing something based on the `processInstanceUuid` value received as argument
                },
                onProcessEnded = {
                    // NOTE: possible processing could involve doing something in the container app (i.e. navigating to a different screen)
                },
                closeModalFunc = { processName ->
                    // NOTE: possible handling could involve doing something differently based on the `processName` value
                },
            ).invoke()
        }
    }
    ...
}
```

### Resume a FlowX process

<Warning>Prior resuming process, make sure the [authentication](#authentication) and [theming](#theming) were correctly set up</Warning>

To resume an existing instance of a FlowX process, after fulfilling all the prerequisites, use the `continueProcess` function:

```kotlin theme={"system"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

#### Parameters

| Name             | Description                                                                                        | Type                                                      | Requirement                       |
| ---------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------- |
| `processUuid`    | The UUID string of the process                                                                     | `String`                                                  | Mandatory                         |
| `isModal`        | Flag indicating whether the process can be closed at anytime by tapping the top-right close button | `Boolean`                                                 | Optional. It defaults to `false`. |
| `onProcessEnded` | Lambda function where you can do additional processing when the continued process ends             | `(() -> Unit)?`                                           | Optional. It defaults to `null`.  |
| `closeModalFunc` | Lambda function where you should handle closing the process when `isModal` flag is `true`          | `(CloseModalProcessScope.(processName: String) -> Unit)?` | Optional. It defaults to `null`.  |

<Tip>
  The returned **[@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable)** function must be included in its own **[Activity](https://developer.android.com/reference/android/app/Activity)**, which is part of (controlled and maintained by) the container application.<br /><br />
  This wrapper activity must display only the `@Composable` returned from the SDK (i.e. it occupies the whole activity screen space).
</Tip>

#### Sample

```kotlin theme={"system"}
class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().continueProcess(
                processUuid = "some process UUID string",
                isModal = true,
                onProcessEnded = {
                    // NOTE: possible processing could involve doing something in the container app (i.e. navigating to a different screen)
                },
                closeModalFunc = { processName ->
                    // NOTE: possible handling could involve doing something differently based on the `processName` value
                },
            ).invoke()
        }
    }
    ...
}
```

### `closeModalFunc` parameter

The `closeModalFunc` parameter is a function defined within the `CloseModalProcessScope` context.

This gives the ability to query for substitution tags or media library items to use them when handling this callback (i.e. showing an snackbar or an alert).

```kotlin theme={"system"}
interface CloseModalProcessScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}
```

#### Get a substitution tag value by key

```kotlin theme={"system"}
fun replaceSubstitutionTag(key: String): String
```

All substitution tags will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns:

* the key's counterpart, if the `key` is valid and found
* the empty string, if the `key` is valid, but not found
* the unaltered string, if the key has the wrong format (i.e. not starting with `@@`)

#### Get a media item url by key

```kotlin theme={"system"}
fun getMediaResourceUrl(key: String): String?
```

All media items will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns the `URL` string of the media resource, or `null`, if not found.

#### Sample

```kotlin theme={"system"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    Flowx.getInstance().startProcess(
        workspaceId = "your workspace id",
        projectId = "your project id",
        processName = "your process name",
        isModal = true,
        onProcessStarted= { ... },
        onProcessEnded = { ... },
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    ).invoke()

    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            onDismissRequest = {},
            title = null,
            text = {
                Text(this@CloseModalProcessConfirmAlert.replaceSubstitutionTag("@@close_message")) // IMPORTANT: call `replaceSubstitutionTag` using the `CloseModalProcessScope` context
            },
            confirmButton = { ... },
            dismissButton = {
                Button(onClick = { show.value = false }) {
                    Text("Cancel")
                }
            }
        )
    }
}
```

### Start an UI Flow

<Warning>Prior starting an UI Flow, make sure the [authentication](#authentication) and [theming](#theming) were correctly set up</Warning>

After performing all the above steps and all the prerequisites are fulfilled, an UI Flow can be started, by using the `startUiFlow` function:

```kotlin theme={"system"}
fun startUiFlow(
    workspaceId: String,
    projectId: String,
    uiFlowName: String,
    params: JSONObject? = null,
): @Composable () -> Unit
```

#### Parameters

| Name          | Description                                                                 | Type         | Requirement                                         |
| ------------- | --------------------------------------------------------------------------- | ------------ | --------------------------------------------------- |
| `workspaceId` | The id of the workspace that contains the project and UI Flow to be started | `String`     | Mandatory                                           |
| `projectId`   | The id of the project containing the UI Flow to be started                  | `String`     | Mandatory                                           |
| `uiFlowName`  | The name of the UI Flow                                                     | `String`     | Mandatory                                           |
| `params`      | The starting params for the process, if any                                 | `JSONObject` | Optional. If omitted, if defaults to `JSONObject()` |

<Tip>
  The returned **[@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable)** function must be included in its own **[Activity](https://developer.android.com/reference/android/app/Activity)**, which is part of (controlled and maintained by) the container application.<br /><br />
  This wrapper activity must display only the `@Composable` returned from the SDK (i.e. it occupies the whole activity screen space).
</Tip>

#### Sample

```kotlin theme={"system"}
class UiFlowActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().startUiFlow(
                workspaceId = "your workspace id",
                projectId = "your project id",
                uiFlowName = "your ui flow name",
                params = JSONObject(),
            ).invoke()
        }
    }
    ...
}
```

## Custom components

The container application should decide which custom component view to provide using the `componentIdentifier` configured in the UI designer.

A custom component receives `data` to populate the view and `actions` available to execute, as described below.<br />
It can also be validated and provide data back into the process when executing an action.

To handle custom components, an *implementation* of the `CustomComponentsProvider` interface should be passed as a parameter when initializing the SDK:

```kotlin theme={"system"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}
```

#### Sample

```kotlin theme={"system"}
class FxCustomComponentsProvider : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> object : CustomComponent {...}
            else -> null
        }
}
```

### CustomComponent

The implementation for providing a custom component is based on creating and binding a user defined [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function, through the `CustomComponent` interface:

```kotlin theme={"system"}
interface CustomComponent {
    /**
     * Returns the [Composable]s for every custom component identifier defined in the FlowX Designer
     */
    val composable: @Composable CustomComponentScope.() -> Unit

    /**
     * This will be called when data is available for the custom component i.e. when the
     * User Task that contains the custom component is displayed.
     *
     * @param data used to populate the custom component
     */
    fun populateUi(data: Any?)

    /**
     * This will be called when actions are available for the custom component i.e. when the
     * User Task that contains the custom component is displayed.
     *
     * @param actions that need to be attached to the custom component (e.g. onClick events)
     */
    fun populateUi(actions: Map<String, CustomComponentAction>)

    /**
     * This will be called when executing an action, when the platform needs to know if the specified/marked components are valid.
     * Defaults to `true`.
     */
    fun validate(): Boolean = true

    /**
     * This will be called when executing an action, on computing the data to be sent as body on the network request.
     * Returning `null` (i.e. default) means it does not contribute with any data to be sent.
     */
    fun saveData(): JSONObject? = null
}
```

<Tip>
  The value for the `data` parameter received in the `populateUi(data: Any?)` could be:<br />

  * `Boolean`
  * `String`
  * `java.lang.Number`
  * `org.json.JSONObject`
  * `org.json.JSONArray`

  The appropriate way to check and cast the data accordingly to the needs must belong to the implementation details of the custom component.
</Tip>

<Tip>
  Both validation and providing data back into process are optional, and, based on the needs, it may be included in the implementation or not.
</Tip>

### CustomComponentScope

The `composable` property of the [CustomComponent](#customcomponent) is a [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function which may be defined and run only within the context of a `CustomComponentScope` receiver.

```kotlin theme={"system"}
val composable: @Composable CustomComponentScope.() -> Unit
```

```kotlin theme={"system"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun executeUploadAction(action: CustomComponentAction, fileUri: Uri, mimeType: String? = null, params: JSONObject? = null)
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

This allows calling predefined SDK methods for executing actions, querying for substitution tags, media resource URLs or obtaining enumerations data, directly from the custom component through the scope itself.

#### Execute action

The custom components which the container app provides may contain FlowX actions available for execution.<br /><br />
These actions are received through the `actions` parameter of the `populateUi(actions: Map<String, CustomComponentAction>)` method.<br /><br />
To run an action (e.g., on a click of a button in the custom component) you need to call the `executeAction` method, through the `CustomComponentScope` context:

```kotlin theme={"system"}
fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
```

##### Parameters

| Name     | Description                                                                 | Type                                                               | Requirement                     |
| -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------- |
| `action` | Action object extracted from the `actions` received in the custom component | `ai.flowx.android.sdk.api.custom.components.CustomComponentAction` | Mandatory                       |
| `params` | Parameters needed to execute the `action`                                   | `JSONObject?`                                                      | Optional. It defaults to `null` |

#### Execute upload action

A specific use case for executing actions from custom components involves uploading files into the FlowX platform.<br /><br />
To run an upload action (e.g., on a click of a button in the custom component) you need to call the `executeUploadAction` method, through the `CustomComponentScope` context:

```kotlin theme={"system"}
fun executeUploadAction(action: CustomComponentAction, fileUri: Uri, mimeType: String? = null, params: JSONObject? = null)
```

##### Parameters

| Name       | Description                                                                 | Type                                                               | Requirement                     |
| ---------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------- |
| `action`   | Action object extracted from the `actions` received in the custom component | `ai.flowx.android.sdk.api.custom.components.CustomComponentAction` | Mandatory                       |
| `fileUri`  | The local URI for the file to be uploaded                                   | `android.net.Uri`                                                  | Mandatory                       |
| `mimeType` | The mimeType of the file to be uploaded                                     | `String?`                                                          | Optional. It defaults to `null` |
| `params`   | Parameters needed to execute the `action`                                   | `JSONObject?`                                                      | Optional. It defaults to `null` |

<Tip>
  It is recommended that a value for the `mimeType` parameter is always provided.<br />
  When missing, the SDK tries computing it internally.
</Tip>

##### Sample

```kotlin expandable theme={"system"}
class FileUploadCustomComponent : CustomComponent {
    var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel: FileUploadViewModel by lazy {
        FileUploadViewModel(actions = actions)
    }

    override val composable: @Composable CustomComponentScope.() -> Unit =
        @Composable {
            val rememberedViewModel = remember { viewModel }
            FileUpload(viewModel = rememberedViewModel)
        }

    override fun populateUi(data: Any?) { ... }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@FileUploadCustomComponent.actions.apply { clear(); putAll(actions) }
    }
}

@Composable
private fun CustomComponentScope.FileUpload(viewModel: FileUploadViewModel) {
    viewModel.setFlowxScope(this@FileUpload)
    val context = LocalContext.current
    val openDocumentLauncher =
        rememberLauncherForActivityResult(ActivityResultContracts.OpenDocument()) { uri ->
            uri?.let { viewModel.executeUploadAction(fileUri = it, mimeType = it.mimeType(context)) }
            Flowx.getInstance().configureUpdateState(enabled = true) // IMPORTANT: restore the SDK internal update mechanism after selecting a file to be uploaded
        }

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Button(
            onClick = {
                Flowx.getInstance().configureUpdateState(enabled = false) // IMPORTANT: disable SDK internal update mechanism while selecting a file to be uploaded
                openDocumentLauncher.launch(listOf("application/pdf").toTypedArray()) // select PDF files only
            }
        ) {
            Text(text = "Upload File")
        }
    }
}

private class FileUploadViewModel(
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    fun executeUploadAction(fileUri: Uri, mimeType: String?) {
        actions["uploadFile"]?.let { action ->
            if (this@FileUploadViewModel::flowxScope.isInitialized) {
                flowxScope.executeUploadAction(
                    action = action,
                    params = null,
                    fileUri = fileUri,
                    mimeType = mimeType,
                )
            }
        }
    }

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }
}

private fun Uri.mimeType(context: Context): String? = context.contentResolver.getType(this)
```

<Info>In order for the upload behave correctly, it's highly IMPORTANT to disable the SDK internal update mechanism while selecting a file.</Info>

#### Get a substitution tag value by key

```kotlin theme={"system"}
fun replaceSubstitutionTag(key: String): String
```

All substitution tags will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns:

* the key's counterpart, if the `key` is valid and found
* the empty string, if the `key` is valid, but not found
* the unaltered string, if the key has the wrong format (i.e. not starting with `@@`)

#### Get a media item url by key

```kotlin theme={"system"}
fun getMediaResourceUrl(key: String): String?
```

All media items will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns the `URL` string of the media resource, or `null`, if not found.

#### Obtain enumeration data

```kotlin theme={"system"}
suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
```

Whenever the container app needs an enumeration data for populating the UI of the custom components, it can request the url, through the `CustomComponentScope` context, using the method above, by providing the `name` (and the `parentName`, if there's a hierarchy defined and the desired enumeration data (`name` is child of `parentName`).

It returns the enumeration data, as an `FxEnumeration` object, or `null`, if not found.

```kotlin theme={"system"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

#### Sample

Among multiple existing custom components, there may be one that:

* allows the input of a value representing an `age`
* the value should be validated (e.g. to be at least 35 years old)
* the value will be passed back into the process
* execute an action, through the `CustomComponentScope` context, to skip setting the age

```kotlin expandable theme={"system"}
class FxCustomComponentsProvider : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            when (componentIdentifier) {
                "other-custom-component-identifier" -> OtherCustomComponent()
                "age" -> AgeCustomComponent()
                else -> null
            }
        }
}

private class AgeCustomComponent() : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = AgeViewModel(data = data, actions = actions)

    override val composable: @Composable CustomComponentScope.() -> Unit
        get() = @Composable {
            Age(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@AgeCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@AgeCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    override fun validate(): Boolean = viewModel.isValid()

    override fun saveData(): JSONObject? = viewModel.buildDataToSave()
}

@Composable
private fun CustomComponentScope.Age(viewModel: AgeViewModel) {
    viewModel.setFlowxScope(this@Age) // IMPORTANT: keep a reference to the custom context/scope in order to access the available predefined SDK methods

    val age by viewModel.ageFlow.collectAsState()
    val error by viewModel.errorFlow.collectAsState()
    val isError by remember(error) { mutableStateOf(error.isNotBlank()) }

    Column {
        OutlinedTextField(
            value = age,
            onValueChange = { viewModel.updateAge(it) },
            modifier = Modifier.fillMaxWidth(),
            label = { Text("Age") },
        )

        if (isError) {
            Text(
                modifier = Modifier.fillMaxWidth(),
                text = error,
                style = TextStyle(fontSize = 12.sp),
                color = Color.Red,
                textAlign = TextAlign.Start,
            )
        }

        TextButton(
            onClick = { viewModel.executeSkipAction() }
        ) {
            Text(text = "Skip")
        }
    }
}

private class AgeViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope // IMPORTANT: keeps the custom context/scope which allows to call the available predefined methods exposed to custom component

    private val _ageFlow = MutableStateFlow("")
    val ageFlow: StateFlow<String> = _ageFlow.asStateFlow()

    private val _error = MutableStateFlow("")
    val errorFlow: StateFlow<String> = _error.asStateFlow()

    fun updateAge(text: String) {
        _ageFlow.value = text
    }

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    fun isValid(): Boolean = ageFlow.value.toIntOrNull().let {
        when {
            it == null -> false.also { _error.update { "Unrecognized format" } }
            it < 35 -> false.also { _error.update { "You have to be at least 35 years old" } }
            else -> true.also { _error.update { "" } }
        }
    }

    fun buildDataToSave(): JSONObject? = ageFlow.value.takeUnless { it.isBlank() }
        ?.let {
            JSONObject(
                """
            {
                "app": {
                    "age": "$it"
                }
            }
            """.trimIndent()
            )
        }

    fun executeSkipAction() {
        actions["skipAction"]?.let {
            if (this@AgeViewModel::flowxScope.isInitialized) { // IMPORTANT: if the custom context/scope was initialized, the action can be safely executed
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("AgeCustomComponent: `skipAction` action was not found")
    }
}

private class OtherCustomComponent() : CustomComponent {
    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            /* add some @Composable implementation */
        }

    override fun populateUi(data: Any?) {
        // extract the necessary data to be used for displaying the custom components
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        // extract the available actions that may be executed from the custom components
    }

    // Optional override, defaults to `true`.
    // Here one can pass validation logic from viewModel (e.g. by calling `viewModel.isValid()`)
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    // Here one can pass data to save from viewModel (e.g. by calling `viewModel.getDataToSave()`)
    override fun saveData(): JSONObject? = null
}
```

## Custom header view for the [STEPPER](../docs/building-blocks/process/navigation-areas#stepper) component

The container app can opt for providing a custom view to use for all the [Stepper](../docs/building-blocks/process/navigation-areas#stepper) components, as a replacement for the built-in header.<br />
The custom view receives `data` to populate its UI, as described below.

To provide a custom header for the [Stepper](../docs/building-blocks/process/navigation-areas#stepper), an *implementation* of the `CustomStepperHeaderProvider` interface should be passed as a parameter when initializing the SDK:

```kotlin theme={"system"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}
```

#### Sample

```kotlin theme={"system"}
class FxCustomStepperHeaderProvider : CustomStepperHeaderProvider {
    override fun provideCustomStepperHeader(): CustomStepperHeader? {
        return object : CustomStepperHeader {...}
    }
}
```

### CustomStepperHeader

To provide the custom header view as a [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function, you have to implement the `CustomStepperHeader` interface:

```kotlin theme={"system"}
interface CustomStepperHeader {
    /**
     * Returns the [Composable]s used to render the stepper header.
     * The received argument contains the stepper header necessary data to render the view.
     */
    val composable: @Composable (data: Data) -> Unit

    interface Data {
        // title for the current step; can be empty or null
        val stepTitle: String?
        // title for the current selected substep; optional;
        // can be empty ("") if not defined or `null` if currently there is no selected substep
        val substepTitle: String?
        // 1-based index of the current step
        val step: Int
        // total number of steps
        val totalSteps: Int
        // 1-based index of the current substep; can be `null` when there are no defined substeps
        val substep: Int?
        // total number of substeps in the current step; can be `null` or `0`
        val totalSubsteps: Int?
    }
}
```

#### Sample

```kotlin theme={"system"}
override fun provideCustomStepperHeader(): CustomStepperHeader? {
    return object : CustomStepperHeader {
        override val composable: @Composable ((CustomStepperHeader.Data) -> Unit)
            get() = @Composable { data ->
                /* add some @Composable implementation which displays the `data` */
            }
    }
}
```

## Custom loaders

The container application can decide to provide custom loaders to be displayed at certain moments based on a given predefined `actionName`.<br />
To provide custom loaders, an *implementation* of the `CustomLoaderProvider` interface should be passed as a parameter when initializing the SDK:

```kotlin theme={"system"}
interface CustomLoaderProvider {
    fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader?
}
```

where the `CustomLoaderProvider.LoaderType` is defined like this:

```kotlin theme={"system"}
interface LoaderType {
    interface StartProcess : LoaderType
    interface ReloadProcess : LoaderType
    interface Action : LoaderType { val name: String }
    interface Upload : LoaderType { val name: String }
}
```

<Info>
  The available types for the `loaderType` parameter are:

  * `LoaderType.StartProcess` - received for overriding the loader displayed when starting a new process
  * `LoaderType.ReloadProcess` - received for overriding the loader displayed when resuming an existing process
  * `LoaderType.Action` - received for overriding the loader displayed while the action having the `name` name is executed
  * `LoaderType.Upload` - received for overriding the loader displayed while the **upload** action having the `name` name is executed

  The `name` property received for the `LoaderType.Action` and `LoaderType.Upload` types represents the name of an action, as defined at process definition time, received for being able to override the loader displayed while that action is executed.
</Info>

<Info>
  Returning an implementation of a `CustomLoader` replaces the built-in platform loader with the provided one for the specified use cases.<br /><br />
  Returning `null` keeps the built-in platform loader for the specified use cases.
</Info>

### CustomLoader

The implementation for providing a custom loader is based on creating and binding a user defined [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function, through the `CustomLoader` interface:

```kotlin theme={"system"}
interface CustomLoader {
    val composable: @Composable CustomLoaderScope.() -> Unit
}
```

### CustomLoaderScope

The `composable` property of the [CustomLoader](#customloader) is a [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function which may be defined and run only within the context of a `CustomLoaderScope` receiver.

```kotlin theme={"system"}
val composable: @Composable CustomLoaderScope.() -> Unit
```

```kotlin theme={"system"}
interface CustomLoaderScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}
```

This allows calling predefined SDK methods for querying for substitution tags and media resource URLs directly from the custom loader through the scope itself.

#### Sample

```kotlin expandable theme={"system"}
class FxCustomLoaderProvider : CustomLoaderProvider {
    override fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader? =
        when (loaderType) {
            is CustomLoaderProvider.LoaderType.StartProcess -> MyCustomLoader(backgroundColor = Color.Black.copy(alpha = 0.38f), indicatorColor = Color.Red)
            is CustomLoaderProvider.LoaderType.ReloadProcess -> MyCustomLoader(backgroundColor = Color.Yellow.copy(alpha = 0.38f), indicatorColor = Color.Green)
            is CustomLoaderProvider.LoaderType.Action -> {
                when (loaderType.name) {
                    "action1" -> ActionCustomLoader()
                    "action2" -> ComplexCustomLoader()
                    else -> null
                }
            }
            is CustomLoaderProvider.LoaderType.Upload -> {
                when (loaderType.name) {
                    "upload1" -> ActionCustomLoader()
                    "upload2" -> ComplexCustomLoader()
                    else -> null
                }
            }
            else -> null
        }
}

class MyCustomLoader(val backgroundColor: Color, val indicatorColor: Color) : CustomLoader {
    override val composable: @Composable (CustomLoaderScope.() -> Unit)
        get() = @Composable {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(color = backgroundColor),
                contentAlignment = Alignment.Center,
            ) {
                CircularProgressIndicator(color = indicatorColor)
                BackHandler(enabled = true) {} // block back navigation
            }
        }
}

class ActionCustomLoader() : CustomLoader {...}

class ComplexCustomLoader() : CustomLoader {
    private val animatedViewModel = AnimatedLoaderViewModel(...)
    override val composable: @Composable (CustomLoaderScope.() -> Unit)
        get() = @Composable {
            AnimatedLoader(viewModel = animatedViewModel)
        }
}

@Composable
private fun CustomLoaderScope.AnimatedLoader(
    viewModel: AnimatedLoaderViewModel
) {
    viewModel.setFlowxScope(this@AnimatedLoader) // IMPORTANT: keep a reference to the custom context/scope in order to access the available predefined SDK methods

    val state by viewModel.loaderState.collectAsStateWithLifecycle()

    Box {
        // use state to build what is to be displayed
    }
}

private class AnimatedLoaderViewModel(...) : ViewModel() {
    private lateinit var flowxScope: CustomLoaderScope // IMPORTANT: keeps the custom context/scope which allows to call the available predefined methods exposed to custom component

    val loaderState: StateFlow<AnimatedLoaderState?> =
        someData
            .process {
                if (this@AnimatedLoaderViewModel::flowxScope.isInitialized) { // IMPORTANT: if the custom context/scope was initialized, the substitution tag can be safely queried
                    flowxScope.replaceSubstitutionTag(it)
                } else {
                    it
                }
            }
            .stateIn(...)

    fun setFlowxScope(scope: CustomLoaderScope) {
        flowxScope = scope
    }
}

```

## Collecting analytics events

To be able to collect analytics events from the SDK, an implementation for the `AnalyticsCollector` functional interface may be provided when initializing the SDK:

```kotlin theme={"system"}
fun interface AnalyticsCollector {
    fun onEvent(event: Event)
}
```

There are two types of events, `Screen` and `Action`, both of them containing some `Data` and an optional `CustomPayload`, as defined at process definition time.

The `Event` is structured like this:

```kotlin theme={"system"}
sealed interface Event {
    interface Screen : Event {
        val data: Screen.Data

        interface Data {
            val value: String
            val customPayload: CustomPayload?
        }
    }

    interface Action : Event {
        val data: Action.Data

        interface Data {
            val value: String
            val screen: String?
            val component: String?
            val label: String?
            val customPayload: CustomPayload?
        }
    }

    sealed interface CustomPayload {
        interface Object : CustomPayload {
            val data: JSONObject
        }

        interface Array : CustomPayload {
            val data: JSONArray
        }
    }
}
```

#### Sample

The implementation can be passed as a lambda, like:

```kotlin theme={"system"}
analyticsCollector = { event ->
    // do whatever is needed (e.g. log the event)
    when (it) {
        is Event.Screen -> {
            val customPayload: String? =
                when (val payload = it.data.customPayload) {
                    is Event.CustomPayload.Object -> payload.data.toString()
                    is Event.CustomPayload.Array -> payload.data.toString()
                    else -> null
                }
            Log.i("Analytics", "Event.Screen(value = ${it.data.value}, customPayload = $customPayload)")
        }

        is Event.Action -> {
            val customPayload: String? =
                when (val payload = it.data.customPayload) {
                    is Event.CustomPayload.Object -> payload.data.toString()
                    is Event.CustomPayload.Array -> payload.data.toString()
                    else -> null
                }
            Log.i("Analytics", "Event.Action(value = ${it.data.value}, screen = ${it.data.screen}, component = ${it.data.component}, label = ${it.data.label}, customPayload = $customPayload)")
        }
    }
}
```

<Info>
  The `value` property represents the identifier set in the process definition.

  For action type events there are some additional properties provided:

  * `component` - The type of component triggering the action
  * `label` - The label of the component, if available. (E.g. title of a button or label of a form element)
  * `screen` - The identifier of the screen containing the component, if set

  The `customPayload` is defined at process definition time, and then processed inside the platform before sending it to being collected.
</Info>

## Handling "Start of a new process"

When an action of type `START_PROJECT` is executed, the `onNewProcessStarted` lambda provided in the `Flowx.getInstance().init(...)` function is invoked.

This callback provides the UUID of the newly started process, which can be used to resume the process by calling the `Flowx.getInstance().continueProcess(...)` method.

It is the responsibility of the container application's developer to implement the necessary logic for displaying the appropriate UI for the newly started process.

#### Sample

One way to handle this is to send a broadcast message to notify the Activity currently displaying the running process.
The Activity should handle the broadcast to reload and display the newly started process identified by `processInstanceUuid` (received in the broadcast intent).

```kotlin theme={"system"}
Flowx.getInstance().init(
    ...
    onNewProcessStarted = { processInstanceUuid ->
        applicationContext.sendBroadcast(
            Intent("some.intent.filter.indentifier").apply {
                putExtra("processInstanceUuid", processInstanceUuid)
                setPackage("your.application.package")
            }
        )
    }
    ...
)

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        setContent {
            val yourBroadcastReceiver = remember {
                YourBroadcastReceiver(handler = { processInstanceUuid -> /* do your own logic to refresh `ProcessContent()` */ })
            }

            val context = LocalContext.current
            LifecycleStartEffect(true) {
                ContextCompat.registerReceiver(context.applicationContext, yourBroadcastReceiver, IntentFilter("some.intent.filter.indentifier"), ContextCompat.RECEIVER_NOT_EXPORTED)
                onStopOrDispose {
                    runCatching {
                        context.applicationContext.unregisterReceiver(yourBroadcastReceiver)
                    }
                }
            }

            ProcessContent()
        }
    }

    @Composable
    private fun ProcessContent(...) {...}
}

class YourBroadcastReceiver(private val handler: (String) -> Unit) : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        intent?.extras?.getString("processInstanceUuid")?.let { processUuid -> handler.invoke(processUuid) }
    }
}
```

## ProGuard / R8

The SDK ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.<br />
These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.<br />
The container app may add additional rules if its specific logic requires them.

## Known issues

* shadows are rendered only on **Android >= 28** having [hardware acceleration](https://developer.android.com/topic/performance/hardware-accel) **enabled**


# Angular SDK
Source: https://docs.flowx.ai/5.9/sdks/angular-renderer

The Angular renderer SDK renders UI configured in the FlowX Designer as a standalone Angular component.

## Angular project requirements

Your app MUST be created using Angular CLI \~20 and MUST use SCSS for styling.

```bash theme={"system"}
npm install -g @angular/cli@20
ng new my-flowx-app
```

<Check>
  To install the npm libraries provided by FlowX.AI you will need to obtain access to the private FlowX.AI Nexus registry. Please consult with your project DevOps.
</Check>

<Info>
  The library requires Angular **\~20**, **npm ≥ 11.0.0** and **node ≥ 24.0.0**.
</Info>

## Installing the library

Use the following command to install the **renderer** library and its required dependencies:

```bash theme={"system"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@20 \
  @types/event-source-polyfill
```

<Warning>
  Replace `<version>` with the correct version corresponding to your platform version.

  To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.
</Warning>

A few configurations are needed in the project's `angular.json`. To successfully link the PDF viewer, add the following declaration in the assets property:

```json theme={"system"}
{
  "glob": "**/*",
  "input": "node_modules/ng2-pdfjs-viewer/pdfjs",
  "output": "/assets/pdfjs"
}
```

## Initial setup

Once installed, `FlxProcessModule` is imported in the `AppModule` as `FlxProcessModule.withConfig({})`.

### Theming

Component theming is done through the `@flowx/angular-theme` library. The theme id is a required input for the renderer SDK component and is used to fetch the theme configuration. The id can be obtained from the admin panel in the themes section.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/2024-04-08%2013.45.10.gif)
</Frame>

### Authorization

<Info>
  It's the responsibility of the client app to implement the authorization flow (using the **OpenID Connect** standard). The renderer SDK expects the authToken to be passed to `flx-process-renderer` as an input.
</Info>

```typescript theme={"system"}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';
import { FlxProcessModule } from '@flowx/angular-sdk';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    HttpClientModule,
    FlxProcessModule.withConfig({
      components: {},
      services: {},
    }),
  ],
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}
```

The `withConfig()` call is required in the app module where the process will be rendered. It accepts a config object where you can register **custom components**, **services**, and **custom validators**.

**Custom components** are referenced by name in the template config for a user task.

**Custom validators** are referenced by name (`currentOrLastYear`) in the template config panel under the validators section of each generated form field.

```typescript theme={"system"}
FlxProcessModule.withConfig({
  components: {
    YourCustomComponentIdentifier: CustomComponent,
  },
  services: {
    NomenclatorService,
    LocalDataStoreService,
  },
  validators: { currentOrLastYear },
})
```

### Custom interceptors

Starting from FlowX SDK version 4.6, the Angular `HttpClientModule` is no longer used internally for HTTP requests. A new mechanism allows you to create custom interceptors.

#### Request interceptors

```typescript theme={"system"}
import { FLX_REQUEST_INTERCEPTORS_CONFIG } from '@flowx/angular-sdk'
import { HttpRequestInterceptor } from '@flowx/core-sdk'

const customHeaderInterceptor: HttpRequestInterceptor[] = [
  {
    onFulfilled: (response) => {
      response.headers['custom-header'] = 'custom-value'
      return response
    },
  }
]

// Add to providers in the main app module
{
  provide: FLX_REQUEST_INTERCEPTORS_CONFIG,
  useValue: customHeaderInterceptor,
}
```

#### Response interceptors

```typescript theme={"system"}
import { FLX_RESPONSE_INTERCEPTORS_CONFIG } from '@flowx/angular-sdk'
import { HttpResponseInterceptor } from '@flowx/core-sdk'

const customErrorInterceptor: HttpResponseInterceptor[] = [
  {
    onRejected: (response) => {
      if (response.status !== 200) {
        console.error('Something went wrong!', response.message)
      }
      return response
    }
  }
]

// Add to providers in the main app module
{
  provide: FLX_RESPONSE_INTERCEPTORS_CONFIG,
  useValue: customErrorInterceptor,
}
```

#### Interceptors that use dependency injection

If you need to use a service in your interceptor, use provider factories with the `deps` property:

```typescript theme={"system"}
const interceptorFactory = (customService: CustomService): HttpRequestInterceptor[] => [{
  onFulfilled: (response) => {
    // use customService here
    return response
  }
}]

// Add to providers in the main app module
{
  provide: FLX_REQUEST_INTERCEPTORS_CONFIG,
  useFactory: (customService: CustomService) => [
    interceptorFactory(customService),
  ],
  deps: [CustomService],
}
```

### Using custom icons

```typescript theme={"system"}
import { FlxIconModule } from '@flowx/angular-ui-toolkit'

const customIconDictionary = {
  'custom-icon': 'custom icon svg'
}

providers: [
  importProvidersFrom(FlxIconModule),
  provideExtraIconSet(customIconDictionary),
]
```

### Analytics

<Info>
  The SDK provides a mechanism for collecting analytics events through a unified `CustomEvent` system. These events can be used to track screens and action events.
</Info>

To use analytics features, import the necessary SDK module:

```typescript theme={"system"}
import {
   ANALYTICS_EVENTS,
   AnalyticsData,
   pushAnalyticsData,
} from '@flowx/core-sdk';
```

#### Emitting analytics events

Analytics events are dispatched using the `pushAnalyticsData(payload: AnalyticsData)` method. The SDK defines two event types:

```typescript theme={"system"}
enum ANALYTICS_EVENTS {
  SCREEN = 'SCREEN',
  ACTION = 'ACTION',
}
```

Each analytics event should be an object of type `AnalyticsData`:

```typescript theme={"system"}
type AnalyticsData = {
  type: ANALYTICS_EVENTS;
  value: string;
  screen?: string;
  component?: string;
  label?: string;
  customPayload?: object;
}
```

<Info>
  The `value` property represents the identifier set in the process definition.

  For `ACTION` type events there are additional properties:

  * `component` - the type of component triggering the action
  * `label` - the label of the component
  * `screen` - the identifier of the screen containing the component, if set
</Info>

#### Listening for analytics events

```typescript theme={"system"}
ngOnInit(): void {
  document.addEventListener('flowx:analytics', this.analyticsListener);
}

analyticsListener = (event: CustomEvent<AnalyticsData>) => {
  console.log('Received flowx:analytics event:', event.detail);
};

ngOnDestroy(): void {
  document.removeEventListener('flowx:analytics', this.analyticsListener);
}
```

<Check>Ensure that you remove the event listener on component destruction to avoid memory leaks.</Check>

#### Custom payload

This allows you to capture and send custom data alongside standard analytics events.

When analytics custom payload is configured in FlowX Designer, the renderer automatically processes variable substitution and includes the resulting data in analytics events.

<Steps>
  <Step title="Receive custom payload configuration">
    The renderer receives the analytics configuration as a JSON string with variable placeholders:

    ```json theme={"system"}
    "analyticsCustomPayload": "{\n \"name\": ${app.input}\n}"
    ```
  </Step>

  <Step title="Process variable substitution">
    The SDK replaces variables with actual values from the process data store:

    <CodeGroup>
      ```json Template theme={"system"}
      {
          "name": "${app.input}",
          "client": "${app.client}",
          "amount": "${app.amount}"
      }
      ```

      ```json Result theme={"system"}
      {
          "name": "john",
          "client": { "id": "123", "name": "John Doe" },
          "amount": 1500
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Add to analytics event">
    The processed payload is included in the analytics event under the `customPayload` property:

    ```typescript theme={"system"}
    {
        type: 'ACTION', // or 'SCREEN'
        info: {
            value: 'Save personal data',
            screen: 'Personal Data',
            component: 'BUTTON',
            label: 'Save',
            customPayload: {
                name: "john",
                client: { id: "123", name: "John Doe" },
                amount: 1500
            }
        }
    }
    ```
  </Step>
</Steps>

***

## Starting a process

### Prerequisites

* **Process name**: You need to know the name of the process you want to start. This name identifies the process in the system.
* **FlowX Project UUID**: You need the UUID of the FlowX Project that contains the process. Obtain it from the FlowX Dashboard.
* **Locale**: You can specify the locale to apply date, currency, and number formatting to data model values.
* **Language**: You can specify the language used to localize enumerations inside the app.

### Getting the project UUID

The project UUID can be obtained from the FlowX Dashboard. Navigate to the Projects section and select the project you want to start a process in. The UUID can be copied from the project actions popover.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/copy_uuid_application.png)

### Getting the process identifier

Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as `processName`.

### Initializing the process renderer

```typescript theme={"system"}
import { Component } from '@angular/core';

@Component({
  selector: 'app-process',
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [processApiPath]="processApiPath"
      [authToken]="authToken"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [processName]="processName"
      [workspaceId]="workspaceId"
      [projectInfo]="projectInfo"
      [organizationId]="organizationId"
      [locale]="'en-US'"
      [language]="'en'"
    />
  `
})
export class ProcessComponent {
  projectInfo = { projectId: 'your-project-uuid' }
}
```

The entry point of the library is the `<flx-process-renderer>` component. A list of accepted inputs is found below:

```html theme={"system"}
<flx-process-renderer
  [apiUrl]="baseApiUrl"
  [processApiPath]="processApiPath"
  [authToken]="authToken"
  [themeId]="themeId"
  [staticAssetsPath]="staticAssetsPath"
  [processName]="processName"
  [processStartData]="processStartData"
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  [organizationId]="organizationId"
  [language]="language"
  [locale]="locale"
  [cache]="cache"
  [buildId]="buildId"
/>
```

**Parameters:**

| Name                | Description                                                                                                                                                                                                                            | Type      | Mandatory | Default value | Example                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------- | ------------- | ---------------------------------------------- |
| `apiUrl`            | Your base URL                                                                                                                                                                                                                          | `string`  | true      | -             | `https://yourDomain.dev`                       |
| `processApiPath`    | Process subpath                                                                                                                                                                                                                        | `string`  | true      | -             | `onboarding`                                   |
| `authToken`         | Authorization token                                                                                                                                                                                                                    | `string`  | true      | -             | `'eyJhbGciOiJSUzI1NiIsIn....'`                 |
| `themeId`           | Theme id used to style the process. Can be obtained from the themes section in the admin                                                                                                                                               | `string`  | true      | -             | `'123-456-789'`                                |
| `staticAssetsPath`  | Path to static assets                                                                                                                                                                                                                  | `string`  | true      | -             | -                                              |
| `projectInfo`       | Defines which FlowX Project will be run. Shape: `{ projectId: string, appVersionId?: string }`                                                                                                                                         | `object`  | true      | -             | `{ projectId: '111-222-333' }`                 |
| `organizationId`    | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). | `string`  | true      | -             | `'10000001-0001-0001-8001-100000000001'`       |
| `processName`       | Identifies a process                                                                                                                                                                                                                   | `string`  | true      | -             | `client_identification`                        |
| `processStartData`  | Data required to start the process                                                                                                                                                                                                     | `json`    | true      | -             | `{ "firstName": "John", "lastName": "Smith" }` |
| `workspaceId`       | Workspace id                                                                                                                                                                                                                           | `string`  | true      | -             | `'8f52744-8403-4e8d....'`                      |
| `language`          | Language used to localize the enumerations inside the app                                                                                                                                                                              | `string`  | false     | `en`          | -                                              |
| `locale`            | Locale used to apply date, currency, and number formatting to data model values                                                                                                                                                        | `string`  | false     | `ro-RO`       | `'en-US'`                                      |
| `isDraft`           | When true, starts the process in draft state                                                                                                                                                                                           | `boolean` | false     | `false`       | -                                              |
| `cache`             | Enable caching of CMS resources (theme, substitution tags, enumerations, media library assets)                                                                                                                                         | `boolean` | false     | `true`        | -                                              |
| `legacyHttpVersion` | Set to `true` only for HTTP versions \< 2, required for SSE to work properly in those environments                                                                                                                                     | `boolean` | false     | `false`       | -                                              |
| `buildId`           | Pinned build identifier                                                                                                                                                                                                                | `string`  | false     | -             | -                                              |
| `customLoader`      | Custom loader components for different loading scenarios                                                                                                                                                                               | `object`  | false     | -             | `{ startProcess: StartLoaderComponent }`       |

#### `projectInfo` shape

```typescript theme={"system"}
projectInfo: {
  projectId: string      // required
  appVersionId?: string  // pin a specific app version
}
```

***

## Custom components

Custom components receive data through the `data$` signal input and are registered via `FlxProcessModule.withConfig({ components: {} })`.

<Warning>
  The object keys passed in `components` **MUST** match the custom component names defined in the FlowX process.
</Warning>

`data$` is a signal holding an `Observable` that emits a `FlxCustomComponentData` object each time the process model updates:

```typescript theme={"system"}
interface FlxCustomComponentData {
  data: any                                                         // value at the configured inputKey path - object or primitive
  actions: ProcessAction[]                                          // metadata for each bound action
  actionsFn: Record<string, (params?: any) => Observable<any>>     // call to trigger a process action; returns an Observable
}
```

```typescript theme={"system"}
@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
  styleUrls: ['./custom-component.component.scss'],
})
export class CustomComponentComponent {
  data$ = input<Observable<FlxCustomComponentData> | null>(null)
}
```

To add a custom component in the template config tree, you need its unique identifier and the data it should receive from the process model.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom.png)

The properties that can be configured are:

* **Identifier** - enables the custom component to be displayed within the component hierarchy and determines available actions.
* **Input keys** - specify the path to process data that components will use to receive their information.
* [**Event Handlers**](../docs/building-blocks/ui-designer/event-handlers) - actions defined here will be made available to the custom component.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom_settings.png#center)
</Frame>

### Prerequisites (before creation)

* **Angular knowledge**: Custom components are created and imported using Angular.
* **Development environment**: Node.js and npm set up for Angular development.
* **Component identifier**: A unique identifier used to reference the component within the app.

### Creating a custom component

1. Create a new Angular component.
2. Implement the HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior.

### Importing the component

Register the component in `FlxProcessModule.withConfig()`:

```typescript theme={"system"}
FlxProcessModule.withConfig({
  components: {
    MyCustomComponentIdentifier: MyCustomComponent,
  },
})
```

### Using the custom component

Once declared, you can configure it in the FlowX Designer.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_component.gif)

### Data input and actions

The custom component receives input data from processes and can include actions extracted from a process. These allow you to configure and interact with the component dynamically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_input_data.png)

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_loader_input.png)
</Frame>

<Warning>
  Make sure that the Angular action names match the names of the process actions.
</Warning>

### Custom component validation

Custom components can validate their own status using the `FLX_VALIDATOR_SERVICE` injection token.

The service exposes:

* `validate(isValid: boolean)` - validates the component
* `saveData(data: any)` - saves data
* `validated$` - Observable for monitoring external submission from the process

```typescript theme={"system"}
import { FLX_VALIDATOR_SERVICE } from '@flowx/angular-sdk'

@Component({
  selector: 'flx-custom-validation',
  imports: [CommonModule, ReactiveFormsModule],
  template: `
    Custom validation:
    <input [formControl]="fc" />
    @if (formSubmitted() && fc.invalid) {
      <span>error</span>
    }
  `
})
export class FlxCustomValidationComponent implements OnInit {
  data$ = input<Observable<any> | null>(null)

  validationService = inject(FLX_VALIDATOR_SERVICE)

  fc = new FormControl('', Validators.required)
  formSubmitted = signal(false)

  ngOnInit(): void {
    this.fc.statusChanges.subscribe((status) => {
      this.validationService.validate(status === 'VALID')
    })
    this.fc.valueChanges.subscribe((value) => {
      this.validationService.saveData({ app: { test1: value, test2: `${value}${value}` } })
    })
    this.validationService.validated$.subscribe(() => {
      this.formSubmitted.set(true)
    })
  }
}
```

***

## Custom validators

You may define custom validators in your FlowX processes and pass their implementation via `FlxProcessModule.withConfig({ validators: {} })`.

<Warning>
  The object keys passed in `validators` **MUST** match the custom validator names defined in the FlowX process.
</Warning>

```typescript theme={"system"}
currentOrLastYear: function currentOrLastYear(AC: AbstractControl): { [key: string]: any } {
  if (!AC) {
    return null;
  }

  const yearDate = moment(AC.value, YEAR_FORMAT, true);
  const currentDateYear = moment(new Date()).startOf('year');
  const lastYear = moment(new Date()).subtract(1, 'year').startOf('year');

  if (!yearDate.isSame(currentDateYear) && !yearDate.isSame(lastYear)) {
    return { currentOrLastYear: true };
  }

  return null;
}
```

<Warning>
  The error that the validator returns **MUST** match the validator name.
</Warning>

***

## Process end handling

The SDK provides a mechanism for handling process completion events through the `(processEnd)` output event. This allows you to implement custom logic when a main process reaches an end state, such as redirecting users or triggering cleanup operations.

The `processEnd` event is triggered when the **main process** (not subprocesses) reaches any terminal state:

* `FINISHED` - process completed successfully
* `FAILED` - process encountered an error
* `ABORTED` - process was manually terminated
* Other terminal states

<Info>
  Only the main process triggers this event. Subprocess completions do not trigger it to avoid unnecessary interruptions during complex process flows.
</Info>

### Implementation

```typescript theme={"system"}
import { Component } from '@angular/core';
import { Router } from '@angular/router';

@Component({
  selector: 'app-process',
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [authToken]="authToken"
      [processName]="processName"
      [processStartData]="processStartData"
      [workspaceId]="workspaceId"
      [processApiPath]="processApiPath"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [projectInfo]="projectInfo"
      [organizationId]="organizationId"
      (processEnd)="onProcessEnd()"
    />
  `
})
export class ProcessComponent {
  constructor(private router: Router) {}

  onProcessEnd(): void {
    console.log('Process has ended');
    this.router.navigate(['/dashboard']);
  }
}
```

***

## Process start handling

The SDK provides a mechanism for reacting to process start events through the `(processStart)` output event. It emits the new `processInstanceUuid` once the main process instance has been created - useful for tracking, deep linking, or storing the instance reference for later resume.

### Implementation

```typescript theme={"system"}
import { Component } from '@angular/core';

@Component({
  selector: 'app-process',
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [authToken]="authToken"
      [processName]="processName"
      [processStartData]="processStartData"
      [workspaceId]="workspaceId"
      [processApiPath]="processApiPath"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [projectInfo]="projectInfo"
      [organizationId]="organizationId"
      (processStart)="onProcessStart($event)"
    />
  `
})
export class ProcessComponent {
  onProcessStart(processInstanceUuid: string): void {
    console.log('process started', processInstanceUuid);
  }
}
```

***

## Custom loader

The SDK provides a mechanism for customizing the loader UI displayed during process execution.

### Configuration

Register custom loaders via `FlxProcessModule.withConfig({ customLoader: {} })`:

```typescript theme={"system"}
import { FlxProcessModule } from '@flowx/angular-sdk';
import { Type } from '@angular/core';

@Component({
  selector: 'app-start-loader',
  template: `
    <div class="custom-start-loader">
      <div class="spinner"></div>
      <p>Starting process...</p>
    </div>
  `
})
export class StartProcessLoaderComponent {}

@Component({
  selector: 'app-specific-action-loader',
  template: `
    <div class="custom-specific-action-loader">
      <div class="spinner"></div>
      <p>Executing specific action...</p>
    </div>
  `
})
export class SpecificActionLoaderComponent {}

@NgModule({
  imports: [
    FlxProcessModule.withConfig({
      customLoader: {
        startProcess: StartProcessLoaderComponent,
        // reloadProcess: ReloadProcessLoaderComponent,
        // defaultAction: DefaultActionLoaderComponent,
        // defaultUpload: DefaultUploadLoaderComponent,
        actions: {
          action1: SpecificActionLoaderComponent,
        },
      },
      components: {},
      services: {},
    }),
  ],
})
export class AppModule {}
```

### API specification

The custom loader configuration accepts an object of type `CustomLoader`:

```typescript theme={"system"}
type CustomLoader = {
  actions?: Record<string, Type<any>>
  startProcess?: Type<any>
  reloadProcess?: Type<any>
  defaultAction?: Type<any>
  defaultUpload?: Type<any>
}
```

#### Loader types

* **`startProcess`** - displayed when starting or resuming a process
* **`reloadProcess`** - displayed when reloading a process
* **`defaultAction`** - default loader for actions when `loaderType` is `'action'`. Used when no specific action loader is found in the `actions` record
* **`defaultUpload`** - default loader for file uploads when `loaderType` is `'upload'`
* **`actions`** - record mapping specific action identifiers to custom loaders. When an action is executed, the SDK checks this record before falling back to `defaultAction`

### Fallback behavior

<Info>
  If no custom loader is provided for a specific type, the SDK automatically falls back to the built-in FlowX loader. This ensures your app continues to function even with partial custom loader configuration.
</Info>

<Tip>
  You can use substitution tags and media library assets within your custom loader components to create rich, branded loading experiences that match your app's design system.
</Tip>

***

## Chat component

To use the `FlxChatRendererComponent`, import the module in your project:

```typescript theme={"system"}
import { FlxChatRendererComponent } from '@flowx/angular-sdk';
```

#### Usage

Include the component in your template:

```html theme={"system"}
<flx-chat-renderer
  [apiUrl]="apiUrl"
  [authToken]="accessToken()"
  [staticAssetsPath]="staticAssetsPath"
  [language]="language()"
  [locale]="locale()"
  [themeId]="themeId()"
  [projectId]="projectId()"
  [workspaceId]="workspaceId()"
  [source]="source()"
  [chatConfig]="chatConfig()"
  [cache]="cache()"
/>
```

Parameters:

| Name               | Description                                   | Type      | Mandatory | Example                           |
| ------------------ | --------------------------------------------- | --------- | --------- | --------------------------------- |
| `apiUrl`           | Your base API URL                             | `string`  | ✅         | `https://yourDomain.dev`          |
| `authToken`        | Authorization token                           | `string`  | ✅         | (retrieved from auth provider)    |
| `staticAssetsPath` | Path for static resources                     | `string`  | ✅         | (set via environment)             |
| `language`         | Language used to localize the chat interface  | `string`  | ✅         | `en`                              |
| `locale`           | Locale setting for date and number formatting | `string`  | ✅         | `en-US`                           |
| `themeId`          | Theme identifier for styling                  | `string`  | ✅         | (retrieved dynamically)           |
| `projectId`        | The FlowX project ID                          | `string`  | ✅         | (retrieved dynamically)           |
| `workspaceId`      | The workspace ID                              | `string`  | ✅         | (retrieved dynamically)           |
| `source`           | Source object with type and id                | `object`  | ✅         | `{ type: 'WORKFLOW', id: '...' }` |
| `chatConfig`       | Chat configuration object                     | `object`  | ✅         | `{ welcomeMessage: '...', ... }`  |
| `cache`            | Enable caching for chat responses             | `boolean` | ❌         | `true`                            |
| `buildId`          | Pinned build identifier                       | `string`  | ❌         | (retrieved dynamically)           |

#### chatConfig parameters

The `chatConfig` object accepts the following properties:

| Name               | Description                                  | Type      | Default value            |
| ------------------ | -------------------------------------------- | --------- | ------------------------ |
| `welcomeMessage`   | Message displayed when chat is first opened  | `string`  | `'Welcome to the chat!'` |
| `thinkingMessage`  | Message displayed while waiting for response | `string`  | `'Thinking...'`          |
| `title`            | Chat window title                            | `string`  | `'Chat'`                 |
| `subtitle`         | Chat window subtitle                         | `string`  | `'Chat subtitle'`        |
| `showChatIcon`     | Whether to display the chat icon             | `boolean` | `true`                   |
| `showSeparator`    | Whether to show separator between messages   | `boolean` | `true`                   |
| `newChatLabel`     | Label for the new chat button                | `string`  | `'New chat'`             |
| `inputPlaceholder` | Placeholder text for the message input field | `string`  | `'Enter your message'`   |
| `maxInputRows`     | Maximum number of rows for the input field   | `number`  | `10`                     |
| `historyTitle`     | Title displayed on the chat history panel    | `string`  | -                        |
| `errorMessage`     | Message shown when an error occurs           | `string`  | `'Error message'`        |
| `canRegenerate`    | Show a regenerate button on responses        | `boolean` | `true`                   |
| `regenerateLabel`  | Label for the regenerate button              | `string`  | `'Regenerate'`           |

***

## Task management component

To use the `FlxTasksManagementComponent`, import the module in your project:

```typescript theme={"system"}
import { FlxTasksManagementComponent } from '@flowx/angular-sdk';
```

#### Usage

Include the component in your template:

```html theme={"system"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId()"
  [language]="language()"
  [themeId]="themeId()"
  [staticAssetsPath]="staticUrl"
  [viewDefinitionId]="viewDefinitionId()"
  [locale]="locale()"
  [buildId]="buildId()"
  [workspaceId]="workspaceId()"
/>
```

Parameters:

| Name               | Description                            | Type              | Mandatory | Example                        |
| ------------------ | -------------------------------------- | ----------------- | --------- | ------------------------------ |
| `apiUrl`           | Endpoint where the tasks are available | `string`          | ✅         | `https://yourDomain.dev/tasks` |
| `authToken`        | Authorization token                    | `string`          | ✅         | (retrieved from local storage) |
| `appId`            | The app ID                             | `string`          | ✅         | (retrieved dynamically)        |
| `viewDefinitionId` | The view configuration identifier      | `string`          | ❌         | (retrieved dynamically)        |
| `workspaceId`      | The workspace ID                       | `string`          | ❌         | (retrieved dynamically)        |
| `themeId`          | The theme identifier                   | `string`          | ❌         | (retrieved dynamically)        |
| `language`         | The selected language                  | `string`          | ❌         | `en`                           |
| `locale`           | The localization setting               | `string`          | ❌         | (retrieved dynamically)        |
| `buildId`          | The current build identifier           | `string`          | ❌         | (retrieved dynamically)        |
| `staticAssetsPath` | Path for static resources              | `string`          | ❌         | (set via environment)          |
| `stages`           | Pre-loaded enumeration stages          | `TMEnumeration[]` | ❌         | -                              |
| `cache`            | Enable caching                         | `boolean`         | ❌         | `true`                         |

***

## Task management public API

The Angular SDK provides a comprehensive public API for building custom task management interfaces. This API allows you to fetch tasks, manage comments, handle task actions, and interact with task data programmatically.

### Importing the service

Inject `PublicTasksService` from `@flowx/angular-sdk`:

```typescript theme={"system"}
import { PublicTasksService } from '@flowx/angular-sdk';
import { inject } from '@angular/core';

export class MyComponent {
  private taskService = inject(PublicTasksService);
}
```

### Available types

```typescript theme={"system"}
import {
  PublicTasksService,
  TMView,
  TMViewTask,
  TMViewColumn,
  TMTaskComment,
  TMTaskHistory,
  TMUser,
  TMEnumerations,
  TMEnumeration,
  TMFilterOperators,
  TMFilters,
  TMSort,
  TMPaginatedResponse,
  TMSetupOptions,
  TMExecuteTaskActions,
  TMOperatorsType,
} from '@flowx/angular-sdk';
```

### Initialization

Before using the task management API, initialize the task manager resources. This fetches the view configuration, enumerations, and filter operators.

```typescript theme={"system"}
this.taskService.getTaskManagerResources({
  apiUrl: 'https://yourDomain.dev/tasks',
  authToken: 'your-auth-token',
  appInfo: { appId: 'app-123' },
  viewId: 'view-456',
  workspaceId: 'workspace-789',
  themeId: 'theme-012', // Optional
  language: 'en', // Optional
  locale: 'en-US', // Optional
  buildId: 'build-345', // Optional
  staticAssetsPath: '/static', // Optional
}).subscribe(({ view, enumerations, filterOperators }) => {
  // Use the view, enumerations, and filterOperators
});
```

**Parameters:**

| Name               | Description                            | Type                | Mandatory | Example                        |
| ------------------ | -------------------------------------- | ------------------- | --------- | ------------------------------ |
| `apiUrl`           | Endpoint where the tasks are available | `string`            | ✅         | `https://yourDomain.dev/tasks` |
| `authToken`        | Authorization token                    | `string`            | ✅         | (retrieved from local storage) |
| `appInfo`          | App information containing appId       | `{ appId: string }` | ✅         | `{ appId: "app-123" }`         |
| `viewId`           | The view configuration identifier      | `string`            | ✅         | (retrieved dynamically)        |
| `workspaceId`      | The workspace ID                       | `string`            | ✅         | (retrieved dynamically)        |
| `themeId`          | The theme identifier                   | `string`            | ❌         | (retrieved dynamically)        |
| `language`         | The selected language                  | `string`            | ❌         | `"en"`                         |
| `locale`           | The localization setting               | `string`            | ❌         | `"en-US"`                      |
| `buildId`          | The current build identifier           | `string`            | ❌         | (retrieved dynamically)        |
| `staticAssetsPath` | Path for static resources              | `string`            | ❌         | (set via environment)          |

**Returns:** Observable emitting an object containing:

* `view`: The view configuration object (`TMView`)
* `enumerations`: Available enumeration options for filters (`TMEnumerations`)
* `filterOperators`: Available filter operators for each column (`TMFilterOperators`)

### Fetching tasks

#### `getViewTasks`

Fetches tasks for a specific view with support for sorting, filtering, pagination, and search.

```typescript theme={"system"}
this.taskService.getViewTasks(
  page,      // page number (0-based)
  sort,      // array of sort configurations
  filters,   // array of filter configurations
  keyword,   // search string
  size       // page size
).subscribe((response) => {
  const tasks = response.content;
});
```

**Parameters:**

| Name      | Description                    | Type          | Mandatory | Example                                       |
| --------- | ------------------------------ | ------------- | --------- | --------------------------------------------- |
| `page`    | Page number (0-based)          | `number`      | ✅         | `0`                                           |
| `sort`    | Array of sort configurations   | `TMSort[]`    | ✅         | `[{ keyName: "priority", direction: "ASC" }]` |
| `filters` | Array of filter configurations | `TMFilters[]` | ✅         | See filter examples below                     |
| `keyword` | Search string for task search  | `string`      | ✅         | `"urgent"`                                    |
| `size`    | Number of items per page       | `number`      | ✅         | `10`                                          |

**Returns:** Observable emitting `TMPaginatedResponse<TMViewTask>` with `content`, `totalElements`, `totalPages`.

#### `getViewTask`

Fetches a specific task by ID and token UUID.

```typescript theme={"system"}
this.taskService.getViewTask(taskId, tokenUuid)
  .subscribe((task) => {
    // Use the task
  });
```

**Parameters:**

| Name        | Description                         | Type     | Mandatory | Example            |
| ----------- | ----------------------------------- | -------- | --------- | ------------------ |
| `taskId`    | The unique task ID                  | `string` | ✅         | `"task-123"`       |
| `tokenUuid` | The token UUID associated with task | `string` | ✅         | `"token-uuid-456"` |

**Returns:** Observable emitting a `TMViewTask` object.

### Task details

#### `getTaskComments`

Fetches all comments for a specific task.

```typescript theme={"system"}
this.taskService.getTaskComments(taskId)
  .subscribe((comments) => {
    // TMTaskComment[]
  });
```

**Parameters:**

| Name     | Description        | Type     | Mandatory | Example      |
| -------- | ------------------ | -------- | --------- | ------------ |
| `taskId` | The unique task ID | `string` | ✅         | `"task-123"` |

**Returns:** Observable emitting an array of `TMTaskComment` objects.

#### `getTaskHistory`

Fetches the history/audit trail for a specific task.

```typescript theme={"system"}
this.taskService.getTaskHistory(taskId)
  .subscribe((history) => {
    // TMTaskHistory[]
  });
```

**Parameters:**

| Name     | Description        | Type     | Mandatory | Example      |
| -------- | ------------------ | -------- | --------- | ------------ |
| `taskId` | The unique task ID | `string` | ✅         | `"task-123"` |

**Returns:** Observable emitting an array of `TMTaskHistory` objects.

#### `getAssignees`

Fetches available assignees for a task, with optional search filtering.

```typescript theme={"system"}
this.taskService.getAssignees(task, { keyword: 'john' })
  .subscribe((users) => {
    // TMUser[]
  });
```

**Parameters:**

| Name    | Description     | Type                  | Mandatory | Example               |
| ------- | --------------- | --------------------- | --------- | --------------------- |
| `task`  | The task object | `TMViewTask`          | ✅         | (task object)         |
| `query` | Search options  | `{ keyword: string }` | ✅         | `{ keyword: "john" }` |

**Note:** The keyword must be at least 4 characters long. If shorter, the Observable will emit an error.

**Returns:** Observable emitting an array of `TMUser` objects.

#### `getBulkAssignees`

Fetches available assignees for multiple tasks in bulk.

```typescript theme={"system"}
this.taskService.getBulkAssignees(
  [{ id: 'task-1', tokenUuid: 'token-1' }, { id: 'task-2', tokenUuid: 'token-2' }],
  { keyword: 'john' }
).subscribe((users) => {
  // TMUser[]
});
```

**Parameters:**

| Name    | Description                                     | Type                                  | Mandatory | Example                                |
| ------- | ----------------------------------------------- | ------------------------------------- | --------- | -------------------------------------- |
| `tasks` | Array of task objects with `id` and `tokenUuid` | `{ id: string; tokenUuid: string }[]` | ✅         | `[{ id: "task-1", tokenUuid: "..." }]` |
| `query` | Search options                                  | `{ keyword: string }`                 | ✅         | `{ keyword: "john" }`                  |

**Returns:** Observable emitting an array of `TMUser` objects.

### Task actions

#### `executeTaskAction`

Executes an action on a specific task (e.g., assign, complete, cancel).

```typescript theme={"system"}
this.taskService.executeTaskAction(action, task, payload)
  .subscribe(() => {
    // action completed
  });
```

**Parameters:**

| Name      | Description                        | Type                   | Mandatory | Example              |
| --------- | ---------------------------------- | ---------------------- | --------- | -------------------- |
| `action`  | The action to execute              | `TMExecuteTaskActions` | ✅         | `TaskActions.ASSIGN` |
| `task`    | The task object                    | `TMViewTask`           | ✅         | (task object)        |
| `payload` | Additional payload (e.g. username) | `any`                  | ❌         | `"john.doe"`         |

**Available actions:**

* `TaskActions.ASSIGN` - assign task to a user
* `TaskActions.COMPLETE` - mark task as complete
* `TaskActions.CANCEL` - cancel the task
* `TaskActions.CHANGE_PRIORITY` - change task priority
* `TaskActions.VIEW` - view task details

#### `bulkUpdate`

Applies an action to multiple tasks at once.

```typescript theme={"system"}
this.taskService.bulkUpdate(
  [{ id: 'task-1', tokenUuid: 'token-1' }, { id: 'task-2', tokenUuid: 'token-2' }],
  TaskActions.COMPLETE,
  'username' // Optional, for assign action
).subscribe(() => {
  // bulk action completed
});
```

**Parameters:**

| Name       | Description                                     | Type                                  | Mandatory | Example                                |
| ---------- | ----------------------------------------------- | ------------------------------------- | --------- | -------------------------------------- |
| `tasks`    | Array of task objects with `id` and `tokenUuid` | `{ id: string; tokenUuid: string }[]` | ✅         | `[{ id: "task-1", tokenUuid: "..." }]` |
| `action`   | The action to execute                           | `TMExecuteTaskActions`                | ✅         | `TaskActions.COMPLETE`                 |
| `username` | Username for assign action                      | `string`                              | ❌         | `"john.doe"`                           |

#### `updatePriority`

Updates the priority of a specific task.

```typescript theme={"system"}
this.taskService.updatePriority(taskId, priority)
  .subscribe(() => {
    // priority updated
  });
```

**Parameters:**

| Name       | Description        | Type     | Mandatory | Example      |
| ---------- | ------------------ | -------- | --------- | ------------ |
| `taskId`   | The unique task ID | `string` | ✅         | `"task-123"` |
| `priority` | New priority value | `number` | ✅         | `5`          |

### Comments management

#### `addComment`

Adds a new comment to a task.

```typescript theme={"system"}
this.taskService.addComment(taskId, { message: 'New comment text' })
  .subscribe((comment) => {
    // TMTaskComment
  });
```

**Parameters:**

| Name      | Description         | Type                  | Mandatory | Example                           |
| --------- | ------------------- | --------------------- | --------- | --------------------------------- |
| `taskId`  | The unique task ID  | `string`              | ✅         | `"task-123"`                      |
| `comment` | Comment data object | `{ message: string }` | ✅         | `{ message: "New comment text" }` |

**Returns:** Observable emitting the created `TMTaskComment` object.

#### `deleteComment`

Removes a comment from a task.

```typescript theme={"system"}
this.taskService.deleteComment(taskId, commentId)
  .subscribe(() => {
    // comment deleted
  });
```

**Parameters:**

| Name        | Description           | Type     | Mandatory | Example         |
| ----------- | --------------------- | -------- | --------- | --------------- |
| `taskId`    | The unique task ID    | `string` | ✅         | `"task-123"`    |
| `commentId` | The unique comment ID | `string` | ✅         | `"comment-456"` |

### Service state management

#### `getView`

Gets the current view configuration.

```typescript theme={"system"}
const view = this.taskService.getView(); // TMView | null
```

#### `getEnumerations`

Gets the current enumerations.

```typescript theme={"system"}
const enumerations = this.taskService.getEnumerations(); // TMEnumerations
```

#### `setView`

Sets the view configuration manually.

```typescript theme={"system"}
this.taskService.setView(view, format);
```

**Parameters:**

| Name     | Description                   | Type      | Mandatory | Example       |
| -------- | ----------------------------- | --------- | --------- | ------------- |
| `view`   | The view configuration object | `TMView`  | ✅         | (view object) |
| `format` | Whether to format the view    | `boolean` | ❌         | `false`       |

### Real-time updates (SSE)

#### `initSse`

Initializes an SSE connection for real-time task updates. Call after `getTaskManagerResources()`.

```typescript theme={"system"}
this.taskService.initSse();
```

#### `getSseEvents`

Gets an Observable stream of SSE events.

```typescript theme={"system"}
this.taskService.getSseEvents()
  .subscribe((event) => {
    console.log('SSE event:', event);
  });
```

**Returns:** Observable emitting `MessageEvent<string>` objects.

#### `closeSseConnection`

Closes the SSE connection.

```typescript theme={"system"}
ngOnDestroy(): void {
  this.taskService.closeSseConnection();
}
```

<Info>
  Always close the SSE connection when your component is destroyed to prevent memory leaks.
</Info>

***

## UI Flow renderer

`FlxUiFlowRendererComponent` renders a full UI Flow (multi-view navigation, breadcrumbs, embedded processes, and an optional chat widget) from a single component.

```typescript theme={"system"}
import { FlxUiFlowRendererComponent } from '@flowx/angular-sdk'
```

#### Usage

```html theme={"system"}
<flx-ui-flow
  [apiUrl]="'https://yourDomain.dev'"
  [authToken]="authToken"
  [processApiPath]="'onboarding'"
  [language]="'en'"
  [locale]="'en-US'"
  [themeId]="themeId"
  [staticAssetsPath]="staticAssetsPath"
  [workspaceId]="workspaceId"
  [projectId]="projectId"
  [organizationId]="organizationId"
  [uiFlowName]="'my-ui-flow'"
  [isDraft]="false"
  [cache]="true"
  [buildId]="buildId"
/>
```

#### Parameters

| Name               | Description                                                                                                                                                                                                                          | Type                                                  | Mandatory |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | --------- |
| `apiUrl`           | Base API URL                                                                                                                                                                                                                         | `string`                                              | ✅         |
| `authToken`        | Authorization token                                                                                                                                                                                                                  | `string`                                              | ✅         |
| `staticAssetsPath` | Static resources base path                                                                                                                                                                                                           | `string`                                              | ✅         |
| `workspaceId`      | Workspace identifier                                                                                                                                                                                                                 | `string`                                              | ✅         |
| `projectId`        | FlowX Project ID                                                                                                                                                                                                                     | `string`                                              | ✅         |
| `organizationId`   | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade. See [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment) | `string`                                              | ✅         |
| `uiFlowName`       | Name of the UI Flow to start                                                                                                                                                                                                         | `string`                                              | ✅         |
| `themeId`          | Theme identifier                                                                                                                                                                                                                     | `string`                                              | ✅         |
| `language`         | UI language                                                                                                                                                                                                                          | `string`                                              | ✅         |
| `locale`           | Date/number formatting locale                                                                                                                                                                                                        | `string`                                              | ✅         |
| `isDraft`          | Render the draft version of the UI Flow                                                                                                                                                                                              | `boolean`                                             | ✅         |
| `cache`            | Enable caching                                                                                                                                                                                                                       | `boolean`                                             | ✅         |
| `buildId`          | Pinned build identifier                                                                                                                                                                                                              | `string`                                              | ❌         |
| `appVersionId`     | Pin a specific app version                                                                                                                                                                                                           | `string`                                              | ❌         |
| `processApiPath`   | Process subpath used by the embedded process renderer                                                                                                                                                                                | `string`                                              | ❌         |
| `startParams`      | Initial query parameters passed to the UI Flow                                                                                                                                                                                       | `Record<string, unknown>`                             | ❌         |
| `customComponents` | Custom component registry                                                                                                                                                                                                            | `Record<string, Type<any>>`                           | ❌         |
| `customValidators` | Custom validator registry                                                                                                                                                                                                            | `Record<string, NgSyncValidator \| NgAsyncValidator>` | ❌         |

<Info>
  Angular uses separate `projectId` and optional `appVersionId?` inputs rather than a nested `appInfo` object.
</Info>

### Starting a UI Flow

#### Prerequisites

* **UI Flow name**: The name of the UI Flow to start, passed as `uiFlowName`.
* **FlowX Project ID**: The `projectId` value, which identifies which project the UI Flow belongs to. Obtain it the same way as for processes: **FlowX Dashboard → Projects → copy UUID from the project actions popover**.
* **Process API path**: The `processApiPath` subpath used by the embedded process renderer when the UI Flow navigates into a full-screen process.

#### Getting the UI Flow name

Open FlowX Designer and navigate to **UI Flows**. The flow name displayed in the list is the value to pass as `uiFlowName`.

#### Initializing the UI Flow renderer

Minimal working example:

```typescript theme={"system"}
import { Component } from '@angular/core';
import { FlxUiFlowRendererComponent } from '@flowx/angular-sdk';

@Component({
  selector: 'app-ui-flow',
  imports: [FlxUiFlowRendererComponent],
  template: `
    <flx-ui-flow
      [apiUrl]="'https://yourDomain.dev'"
      [authToken]="authToken"
      [processApiPath]="'onboarding'"
      [language]="'en'"
      [locale]="'en-US'"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [workspaceId]="workspaceId"
      [projectId]="projectId"
      [organizationId]="organizationId"
      [uiFlowName]="uiFlowName"
      [isDraft]="false"
      [cache]="true"
    />
  `
})
export class UiFlowContainerComponent {
  authToken = '...'
  themeId = '...'
  staticAssetsPath = '...'
  workspaceId = '...'
  projectId = '...'
  organizationId = '...'
  uiFlowName = '...'
}
```

#### Passing initial parameters: `startParams`

Use `startParams` to inject query-string key/value pairs into the UI Flow at startup. The values are available inside the flow as URL query parameters.

```html theme={"system"}
<flx-ui-flow
  [apiUrl]="apiUrl"
  [authToken]="authToken"
  [projectId]="projectId"
  [workspaceId]="workspaceId"
  [organizationId]="organizationId"
  [uiFlowName]="uiFlowName"
  [themeId]="themeId"
  [language]="language"
  [locale]="locale"
  [staticAssetsPath]="staticAssetsPath"
  [isDraft]="false"
  [cache]="true"
  [startParams]="{ referralCode: 'REF123', skipIntro: true }"
/>
```

<Info>
  `startParams` is read once at initialization. To trigger a full re-initialization, change one of the required inputs such as `uiFlowName`.
</Info>

***

## Utility API

These functions and pipes are exported from `@flowx/angular-sdk` and can be used independently of the renderer components.

```typescript theme={"system"}
import {
  getEnumeration,
  getStaticAsset,
  getSubstitutionTag,
  FlxLocalizePipe,
} from '@flowx/angular-sdk'
```

<Warning>
  These methods should only be used inside custom components and within a process context, because internal requests depend on the presence of running project details.
</Warning>

#### `getEnumeration`

Async function to fetch enumeration values.

```typescript theme={"system"}
// get an enumeration by name
const enumeration = await getEnumeration('enumerationName')

// get enumeration with a parent
const enumeration = await getEnumeration('enumerationName', 'parentName')

// get enumeration and cache the result for subsequent calls
const enumeration = await getEnumeration('enumerationName', null, true)
```

| Parameter    | Description                           | Type      | Mandatory |
| ------------ | ------------------------------------- | --------- | --------- |
| `name`       | Enumeration name                      | `string`  | ✅         |
| `parentName` | Parent enumeration name for cascading | `string`  | ❌         |
| `cached`     | Use cached result when available      | `boolean` | ❌         |

#### `getStaticAsset`

Resolves a static asset URL by its key.

```typescript theme={"system"}
const url = getStaticAsset(key)
```

#### `getSubstitutionTag`

Resolves a substitution tag value by its key.

```typescript theme={"system"}
const value = getSubstitutionTag(key)
```

#### `FlxLocalizePipe`

Standalone pipe for managing translations. Import it in the module or component where you want to use it:

```typescript theme={"system"}
import { FlxLocalizePipe } from '@flowx/angular-sdk'

// In your module or component imports:
imports: [
  FlxLocalizePipe
]
```

Use in a template:

```html theme={"system"}
<span>{{ 'hello' | flxLocalize }}</span>
```

Use in a component class:

```typescript theme={"system"}
const localize = new FlxLocalizePipe()
const translatedText = localize.transform('@@substitution_tag')
```

***

## Custom CSS

The renderer SDK allows you to pass custom CSS classes on any component inside the process. These classes are applied to the component's root element.

To add a CSS custom class to a component, define the class in the process designer by navigating to the styles tab of the component, expanding the **Advanced** accordion and writing the CSS class.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/add_css_class.gif)

<Warning>
  The classes will be applied last on the element, so they override the classes already defined on the element.
</Warning>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/css_class_inspector.png)

***

## Storybook

Below you find a Storybook which demonstrates how components behave under different states, props, and conditions. It allows you to preview and interact with individual UI components in isolation, without the need for a full-fledged app:

<Card title="Storybook" href="https://storybooks.flowxai.dev/" icon="book" />


# iOS SDK
Source: https://docs.flowx.ai/5.9/sdks/ios-renderer

Install and configure the FlowX.AI iOS SDK to render process-driven UI in native iOS apps. Requires iOS 15+ and Swift 5.7.

# Using the iOS Renderer

## iOS Project Requirements

The minimum requirements are:

* iOS 15
* Swift 5.7

## Installing the library

The iOS Renderer is available through Cocoapods.

### Cocoapods

#### Prerequisites

* Cocoapods gem installed

#### Cocoapods private trunk setup

Add the private trunk repo to your local Cocoapods installation with the command:

```ruby theme={"system"}
pod repo add flowx-specs git@github.com:flowx-ai-external/flowx-ios-specs.git
```

#### Adding the dependency

Add the source of the private repository in the Podfile

```ruby theme={"system"}
source 'git@github.com:flowx-ai-external/flowx-ios-specs.git'
```

Add a post install hook in the Podfile setting `BUILD_LIBRARY_FOR_DISTRIBUTION` to `YES`.

```ruby theme={"system"}
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end
```

Add the pod and then run `pod install`

```ruby theme={"system"}
pod 'FlowXRenderer'
```

Example

```ruby theme={"system"}
source 'https://github.com/flowx-ai-external/flowx-ios-specs.git'
source 'https://github.com/CocoaPods/Specs.git'

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

target 'AppTemplate' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  
  # Pods for AppTemplate
  pod 'FlowXRenderer'
  
  target 'AppTemplateTests' do
    inherit! :search_paths
    # Pods for testing
  end
  
  target 'AppTemplateUITests' do
    # Pods for testing
  end
  
end
```

### Library dependencies

* Alamofire
* SDWebImageSwiftUI
* SDWebImageSVGCoder

## Configuring the library

The SDK has 2 configurations, available through shared instances: `FXConfig` which holds general purpose properties, and `FXSessionConfig` which holds user session properties.

It is recommended to call the `FXConfig` configuration method at app launch.

Call the FXSessionConfig configure method after the user logs in and a valid user session is available.

### FXConfig

This config is used for general purpose properties.

#### Properties

| Name                  | Description                                                                      | Type              | Requirement                    |
| --------------------- | -------------------------------------------------------------------------------- | ----------------- | ------------------------------ |
| baseURL               | The base URL used for REST networking                                            | String            | Mandatory                      |
| enginePath            | The process engine url path component                                            | String            | Mandatory                      |
| imageBaseURL          | The base URL used for static assets                                              | String            | Mandatory                      |
| organizationId        | The UUID of the FlowX organization the host app belongs to                       | String            | Mandatory                      |
| locale                | The locale used for localization                                                 | String            | Mandatory. Defaults to "en-us" |
| language              | The language used for retrieving enumerations and substitution tags              | String            | Mandatory. Defaults to "en"    |
| logLevel              | Enum value indicating the log level logging. Default is none                     | FXLogLevel        | Optional                       |
| additionalHttpHeaders | Additional HTTP headers included in all SDK network requests                     | \[String: String] | Optional. Defaults to \[:]     |
| cacheDocuments        | Whether to cache documents locally                                               | Bool              | Optional. Defaults to true     |
| updateStateEnabled    | Whether to check and update process state when the app returns to the foreground | Bool              | Optional. Defaults to true     |

<Info>
  `organizationId` is the FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment).
</Info>

**Sample**

```swift theme={"system"}
FXConfig.sharedInstance.configure { (config) in
    config.baseURL = myBaseURL
    config.enginePath = "engine"
    config.imageBaseURL = myImageBaseURL
    config.organizationId = myOrganizationUuid
    config.locale = "en-us" 
    config.language = "en" 
    config.logLevel = .verbose
    config.additionalHttpHeaders = ["X-Custom-Header": "value"]
    config.cacheDocuments = true
    config.updateStateEnabled = true
}
```

#### Changing the current language

The current language and locale can be changed after the initial configuration, by calling the `changeLocaleSettings` method:

```swift theme={"system"}
public func changeLocaleSettings(locale: String?,
                                 language: String?)
```

```swift theme={"system"}
FXConfig.sharedInstance.changeLocaleSettings(locale: "ro-ro",
                                             language: "en")
```

<Info>
  For locale, use the format BCP 47. BCP 47 is the standard for representing language and region codes, here is a [link](https://www.w3.org/International/articles/language-tags/) to the BCP 47 specification.
  An example of BCP 47 is `en-us` (language code - `en` and region code - `us`).
</Info>

### FXSessionConfig

This config is used for providing networking or auth session-specific properties.

The library expects either the JWT access token or an Alamofire Session instance managed by the container app. In case a session object is provided, the request adapting should be handled by the container app.

#### Properties

| Name           | Description                                         | Type    |
| -------------- | --------------------------------------------------- | ------- |
| sessionManager | Alamofire session instance used for REST networking | Session |
| token          | JWT authentication access token                     | String  |

#### Sample for access token

```swift theme={"system"}
    ...
    func configureFlowXSession() {
        FXSessionConfig.sharedInstance.configure { config in
            config.token = myAccessToken
        }
    }   

```

#### Sample for session

```swift theme={"system"}
import Alamofire
```

```swift theme={"system"}
    ...
    func configureFlowXSession() {
        FXSessionConfig.sharedInstance.configure { config in
            config.sessionManager = Session(interceptor: MyRequestInterceptor())
        }
    }   

```

```swift theme={"system"}
class MyRequestInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest, for session: Session, completion: @escaping (Swift.Result<URLRequest, Error>) -> Void) {
        var urlRequest = urlRequest
        urlRequest.setValue("Bearer " + accessToken, forHTTPHeaderField: "Authorization")
        completion(.success(urlRequest))
    }    
}
```

### Theming

<Warning>Make sure the `FXSessionConfig` configure method was called with a valid session before setting up the theme.</Warning>

Before starting or resuming a process, the theme setup API should be called.
The start or continue process APIs should be called only after the theme setup was completed.

### Theme setup

The setup theme is called using the shared instance of `FXTheme`

```swift theme={"system"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```

* `uuid` - the UUID of the theme configured in the FlowX Designer.

* `workspaceId` - the UUID of the workspace the theme belongs to.

* `localFileUrl` - optional parameter for providing a fallback theme file, in case the fetch theme request fails.

* `appearance` - optional SwiftUI `ColorScheme` (`.light` or `.dark`) used to render the theme. Defaults to `.light`.

* `completion` - a completion closure called when the theme setup finishes.

In addition to the `completion` parameter, FXTheme's shared instance also provides a Combine publisher named `themeFetched` which sends `true` if the theme setup was finished.

#### Sample

```swift theme={"system"}
FXTheme.sharedInstance.setupTheme(withUuid: myThemeUuid,
                                  workspaceId: workspaceUuid,
                                  localFileUrl: Bundle.main.url(forResource: "theme", withExtension: "json"),
                                  appearance: .light,
                                  completion: {
    print("theme setup finished")
})
```

```swift theme={"system"}
...
    var subscription: AnyCancellable?

    func myMethodForThemeSetupFinished() {
        subscription = FXTheme.sharedInstance.themeFetched.sink { result in
            if result {
                DispatchQueue.main.async {
                    // you can now start/continue a process
                }
            }
        }
    }
}
    
...

```

## Using the library

### Public API

The library's public APIs described in this section are called using the shared instance of FlowX, `FlowX.sharedInstance`.

### How to start and end FlowX session

After all the configurations are set, you can start a FlowX session by calling the `startSession()` method.

This is optional, as the session starts lazily when the first process is started.

`FlowX.sharedInstance.startSession()`

When you want to end a FlowX session, you can call the `endSession()` method. This also does a complete clean-up of the started processes.

You might want to use this method in a variety of scenarios, for instance when the user logs out.

`FlowX.sharedInstance.endSession()`

### How to start a process

There are 3 methods available for starting a FlowX process.
The container app is responsible with presenting the navigation controller or tab controller holding the process navigation.

1. Start a process which renders inside an instance of `UINavigationController` or `UITabBarController`, depending on the BPMN diagram of the process.

The controller to be presented is provided through the `completion` closure parameter of the method.

<Tip>Use this method when you want the process to be rendered inside a controller themed using the FlowX Theme defined in the FlowX Designer, regardless of the navigation type configured for the process.</Tip>

```swift theme={"system"}
public func startProcess(workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         completion: ((UIViewController?, String) -> Void)?,
                         onProcessEnded: (() -> Void)? = nil)
```

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the process

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the process.

* `completion` - a completion closure which passes either an instance of `UINavigationController` or `UITabBarController` to be presented, alongside the started process instance UUID. The UUID is an empty string if the process failed to start.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

2. Start a process which renders inside a provided instance of a `UINavigationController`.

<Tip>Use this method when you want the process to be rendered inside a custom instance of `UINavigationController`.<br />Optionally you can pass an instance of `FXNavigationViewController`, which has the appearance set in the FlowX Theme, using the `FXNavigationViewController`s class func `FXNavigationViewController.navigationController()`.</Tip>

If you use this method, make sure that the process does not use a tab controller as root view.

```swift theme={"system"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessStarted: ((String) -> Void)? = nil,
                         onProcessEnded: (() -> Void)? = nil)
```

* `navigationController` - the instance of UINavigationController which will hold the process navigation stack

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the process

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the process.

* `onProcessStarted` - an optional closure called after the process has been started, providing the process instance UUID.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

3. Start a process which renders inside a provided instance of a `UITabBarController`.

<Tip>Use this method when you want the process to be rendered inside a custom instance of `UITabBarController`.</Tip>

<Warning>If you use this method, make sure that the process has a tab controller as root view.</Warning>

```swift theme={"system"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessStarted: ((String) -> Void)? = nil,
                         onProcessEnded: (() -> Void)? = nil)
```

* `tabBarController` - the instance of UITabBarController which will hold the process navigation

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the process

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the process.

* `onProcessStarted` - an optional closure called after the process has been started, providing the process instance UUID.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

#### Sample

```swift theme={"system"}
FlowX.sharedInstance.startProcess(workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true) { processRootViewController, processInstanceUuid in
    if let processRootViewController = processRootViewController {
        processRootViewController.modalPresentationStyle = .overFullScreen
        self.present(processRootViewController, animated: false)
    }
    //TODO use processInstanceUuid if needed
} onProcessEnded: { [weak self] in
    //TODO handle process end
}
```

or

```swift theme={"system"}
FlowX.sharedInstance.startProcess(navigationController: processNavigationController,
                                  workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true,
                                  onProcessStarted: { processInstanceUuid in
    //TODO use processInstanceUuid if needed
}, onProcessEnded: { [weak self] in
    //TODO handle process end
})

self.present(processNavigationController, animated: true, completion: nil)
```

or

```swift theme={"system"}
FlowX.sharedInstance.startProcess(tabBarController: processTabController,
                                  workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true,
                                  onProcessStarted: { processInstanceUuid in
    //TODO use processInstanceUuid if needed
}, onProcessEnded: { [weak self] in
    //TODO handle process end
})

self.present(processTabController, animated: true, completion: nil)
```

### How to start a UI Flow

UI Flows are lightweight, screen-driven flows defined in the FlowX Designer. They run client-side on top of a data model, without requiring a BPMN process instance on the engine.

The container app is responsible with presenting the controller passed in the `completion` closure.

```swift theme={"system"}
public func startUIFlow(workspaceId: String,
                        projectId: String,
                        name: String,
                        params: [String: Any]?,
                        isModal: Bool = false,
                        showLoader: Bool = false,
                        completion: ((UIViewController?) -> Void)?)
```

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the UI Flow

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the UI Flow navigation is modally displayed. When the navigation is displayed modally, a close bar button item is displayed on each screen.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the UI Flow.

* `completion` - a completion closure which passes either an instance of `UINavigationController` or `UITabBarController` to be presented, depending on the navigation configured for the UI Flow.

#### Sample

```swift theme={"system"}
FlowX.sharedInstance.startUIFlow(workspaceId: workspaceUuid,
                                 projectId: applicationUuid,
                                 name: uiFlowName,
                                 params: [:],
                                 isModal: true,
                                 showLoader: true) { rootViewController in
    if let rootViewController = rootViewController {
        rootViewController.modalPresentationStyle = .overFullScreen
        self.present(rootViewController, animated: false)
    }
}
```

### How to resume an existing process

There are 3 methods available for resuming a FlowX process.
The container app is responsible with presenting the navigation controller or tab controller holding the process navigation.

1. Continue a process which renders inside an instance of `UINavigationController` or `UITabBarController`, depending on the BPMN diagram of the process.

The controller to be presented will be provided inside the `completion` closure parameter of the method.

<Tip>Use this method when you want the process to be rendered inside a controller themed using the FlowX Theme defined in the FlowX Designer. </Tip>

```swift theme={"system"}
public func continueExistingProcess(uuid: String,
                                    name: String,
                                    isModal: Bool = false,
                                    showLoader: Bool = false,
                                    completion: ((UIViewController?) -> Void)? = nil,
                                    onProcessEnded: (() -> Void)? = nil)
```

* `uuid` - the UUID string of the process

* `name` - the name of the process

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when resuming the process.

* `completion` - a completion closure which passes either an instance of `UINavigationController` or `UITabBarController` to be presented.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

2. Continue a process which renders inside a provided instance of a `UINavigationController`.

<Tip>Use this method when you want the process to be rendered inside a custom instance of `UINavigationController`.<br />Optionally you can pass an instance of `FXNavigationViewController`, which has the appearance set in the FlowX Theme, using the `FXNavigationViewController`s class func `FXNavigationViewController.navigationController()`.</Tip>

If you use this method, make sure that the process does not use a tab controller as root view.

```swift theme={"system"}
public func continueExistingProcess(uuid: String,
                                    name: String,
                                    navigationController: UINavigationController,
                                    isModal: Bool = false,
                                    showLoader: Bool = false,
                                    onProcessEnded: (() -> Void)? = nil)
```

* `uuid` - the UUID string of the process

* `name` - the name of the process

* `navigationController` - the instance of UINavigationController which will hold the process navigation stack

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when resuming the process.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

3. Continue a process which renders inside a provided instance of a `UITabBarController`.

<Tip>Use this method when you want the process to be rendered inside a custom instance of `UITabBarController`.</Tip>

<Warning>If you use this method, make sure that the process has a tab controller as root view.</Warning>

```swift theme={"system"}
public func continueExistingProcess(uuid: String,
                                    name: String,
                                    tabBarController: UITabBarController,
                                    isModal: Bool = false,
                                    showLoader: Bool = false,
                                    onProcessEnded: (() -> Void)? = nil)
```

* `uuid` - the UUID string of the process

* `name` - the name of the process

* `tabBarController` - the instance of UITabBarController which will hold the process navigation

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when resuming the process.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

#### Sample

```swift theme={"system"}
FlowX.sharedInstance.continueExistingProcess(uuid: uuid,
                                             name: processName,
                                             isModal: true) { processRootViewController in
    if let processRootViewController = processRootViewController {
        processRootViewController.modalPresentationStyle = .overFullScreen
        self.present(processRootViewController, animated: true)
    }
} onProcessEnded: { [weak self] in
    
}
```

or

```swift theme={"system"}
FlowX.sharedInstance.continueExistingProcess(uuid: uuid,
                                             name: processName,
                                             navigationController: processNavigationController,
                                             isModal: true)
processNavigationController.modalPresentationStyle = .overFullScreen

self.present(processNavigationController, animated: true, completion: nil)
```

or

```swift theme={"system"}
FlowX.sharedInstance.continueExistingProcess(uuid: uuid,
                                             name: processName,
                                             tabBarController: processTabBarController,
                                             isModal: false)
processTabBarController.modalPresentationStyle = .overFullScreen

self.present(processTabBarController, animated: true, completion: nil)
```

### How to resume the latest process

You can resume the most recently started process using `continueLatestProcess`. This method uses the internally tracked latest process instance UUID.

```swift theme={"system"}
public func continueLatestProcess(name: String,
                                  navigationController: UINavigationController,
                                  isModal: Bool = false)
```

* `name` - the name of the process

* `navigationController` - the instance of UINavigationController which will hold the process navigation stack

* `isModal` - a boolean indicating whether the process navigation is modally displayed

#### Sample

```swift theme={"system"}
FlowX.sharedInstance.continueLatestProcess(name: processName,
                                           navigationController: processNavigationController,
                                           isModal: true)

self.present(processNavigationController, animated: true, completion: nil)
```

### How to end a process

You can manually end a process by calling the `stopProcess(name: String)` method.

This is useful when you want to explicitly ask the FlowX shared instance to clean up the instance of the process sent as parameter.

For example, it could be used for modally displayed processes that are dismissed by the user, in which case the `dismissRequested(forProcess process: String, navigationController: UINavigationController)` method of the FXDataSource will be called.

#### Sample

```swift theme={"system"}
FlowX.sharedInstance.stopProcess(name: processName)
```

### FXDataSource

The library offers a way of communication with the container app through the `FXDataSource` protocol.

The data source is a public property of FlowX shared instance.

`public weak var dataSource: FXDataSource?`

```swift theme={"system"}
public protocol FXDataSource: AnyObject {
    func controllerFor(componentIdentifier: String) -> FXController?
    
    func viewFor(componentIdentifier: String) -> FXView?
    
    func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView?

    func navigationController() -> UINavigationController?

    func errorReceivedForAction(name: String?)
    
    func validate(validatorName: String, value: Any, params: [String]?) -> Bool
    
    func dismissRequested(forProcess process: String, navigationController: UINavigationController)
    
    func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView?

    func collect(event: AnalyticsEvent)
 
    func newProcessStarted(processInstanceUuid: String)
    
    func customLoader(type: CustomLoaderType) -> AnyView?
}
```

* `func controllerFor(componentIdentifier: String) -> FXController?`

This method is used for providing a custom component using UIKit UIViewController, identified by the componentIdentifier argument.

* `func viewFor(componentIdentifier: String) -> FXView?`

This method is used for providing a custom component using UIKit UIView, identified by the componentIdentifier argument.

* `func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView?`

This method is used for providing a custom component using SwiftUI View, identified by the componentIdentifier argument.
A view model is provided as an ObservableObject to be added as @ObservedObject inside the SwiftUI view for component data observation.

* `func navigationController() -> UINavigationController?`

This method is used for providing a navigation controller. It can be either a custom `UINavigationController` class, or just a regular `UINavigationController` instance themed by the container app.

* `func errorReceivedForAction(name: String?)`

This method is called when an error occurs after an action is executed.

* `func validate(validatorName: String, value: Any, params: [String]?) -> Bool`

This method is used for custom validators. It provides the name of the validator, the value to be validated, and an optional array of parameter strings. The method returns a boolean indicating whether the value is valid or not.

* `func dismissRequested(forProcess process: String, navigationController: UINavigationController)`

This method is called, on a modally displayed process navigation, when the user attempts to dismiss the modal navigation. Typically it is used when you want to present a confirmation pop-up.

The container app is responsible with dismissing the UI and calling the stop process APIs.

* `func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView?`

This method is used for providing a custom SwiftUI view for the stepper navigation header.

* `func collect(event: AnalyticsEvent)`

This method is used for collecting analytics events from the SDK. The parameter is a `AnalyticsEvent` enum, which can represent a screen or an action.

* `func newProcessStarted(processInstanceUuid: String)`

This method is used for handling the start of another main process as a result of a `START_PROJECT` action. The parameter is the uuid of the process instance. The container app is responsible for dismissing the navigation of the current process and displaying the new process navigation.

* `func customLoader(type: CustomLoaderType) -> AnyView?`

This method is used for providing a custom loader view. It is called by the SDK when a loading indicator needs to be displayed. The `type` parameter indicates the context in which the loader is shown. Return `nil` to use the default loader.

This method has a default implementation that returns `nil`.

```swift theme={"system"}
public enum CustomLoaderType {
    case startProcess
    case reloadProcess
    case action(String?)
    case upload(String?)
}
```

* `startProcess` - the loader is displayed when a process is being started
* `reloadProcess` - the loader is displayed when a process is being reloaded
* `action(String?)` - the loader is displayed when an action is being executed. The associated value is the action name, if available.
* `upload(String?)` - the loader is displayed for an in-progress file upload. The associated value is the action name, if available.

#### Sample

```swift theme={"system"}
class MyFXDataSource: FXDataSource {
    func controllerFor(componentIdentifier: String) -> FXController? {
        switch componentIdentifier {
        case "customComponent1":
            let customComponent: CustomViewController = viewController()
            return customComponent
        default:
            return nil
        }
    }
    
    func viewFor(componentIdentifier: String) -> FXView? {
        switch componentIdentifier {
        case "customComponent2":
            return CustomView()
        default:
            return nil
        }
    }
    
    func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView? {
        switch componentIdentifier {
        case "customComponent2":
            return AnyView(SUICustomView(viewModel: customComponentViewModel))
        default:
            return nil
        }
    }
    
    func navigationController() -> UINavigationController? {
        nil
    }
    
    func errorReceivedForAction(name: String?) {
        
    }
    
    func validate(validatorName: String, value: Any, params: [String]?) -> Bool {
        switch validatorName {
        case "myCustomValidator":
            let myCustomValidator = MyCustomValidator(input: value as? String)
            return myCustomValidator.isValid()
        default:
            return true
        }
    }
    
    func dismissRequested(forProcess process: String, navigationController: UINavigationController) {
        navigationController.dismiss(animated: true, completion: nil)
        FlowX.sharedInstance.stopProcess(name: process)
    }

    func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView? {
        return AnyView(CustomStepperHeaderView(stepViewModel: stepViewModel))
    }

    func collect(event: AnalyticsEvent) {
        //TODO: collect event using the desired analytics tool.
    }
 
    func newProcessStarted(processInstanceUuid: String) {
        //TODO present new process instance navigation
    }

    func customLoader(type: CustomLoaderType) -> AnyView? {
        switch type {
        case .startProcess:
            return AnyView(MyStartProcessLoader())
        case .reloadProcess:
            return AnyView(MyReloadLoader())
        case .action(let actionName):
            return AnyView(MyActionLoader(actionName: actionName))
        case .upload(let actionName):
            return AnyView(MyUploadLoader(actionName: actionName))
        }
    }

}
```

### Custom components

#### FXController

FXController is an open class subclassing UIViewController, which helps the container app provide full custom screens the renderer.
It needs to be subclassed for each custom screen.

<Warning>Use this only when the custom component configured in the UI Designer is the root component of the User Task node.</Warning>

```swift theme={"system"}
open class FXController: UIViewController {
    
    internal(set) public var data: Any?
    internal(set) public var actions: [ProcessActionModel]?

    open func titleForScreen() -> String? {
        return nil
    }
    
    open func populateUI() {
        
    }
    
    open func updateUI() {
        
    }
    
}
```

* `internal(set) public var data: Any?`

`data` is the property, containing the data model for the custom component. The type is Any, as it could be a primitive value, a dictionary or an array, depending on the component configuration.

* `internal(set) public var actions: [ProcessActionModel]?`

`actions` is the array of actions provided to the custom component.

* `func titleForScreen() -> String?`

This method is used for setting the screen title. It is called by the renderer when the view controller is displayed.

* `func populateUI()`

This method is called by the renderer, after the controller has been presented, when the data is available.

This will happen asynchronously. It is the container app's responsibility to make sure that the initial state of the view controller does not have default/residual values displayed.

* `func updateUI()`

This method is called by the renderer when an already displayed view controller needs to update the data shown.

#### FXView

FXView is a protocol that helps the container app provide custom UIKit subviews to the renderer. It needs to be implemented by `UIView` instances. Similar to `FXController` it has data and actions properties and a populate method.

```swift theme={"system"}
public protocol FXView: UIView {
    var data: Any? { get set }
    var actions: [ProcessActionModel]? { get set }

    func populateUI()
}
```

* `var data: Any?`

`data` is the property containing the data model for the custom view. The type is Any, as it could be a primitive value, a dictionary or an array, depending on the component configuration.

* `var actions: [ProcessActionModel]?`

`actions` is the array of actions provided to the custom view.

* `func populateUI()`

This method is called by the renderer after the screen containing the view has been displayed.

It is the container app's responsibility to make sure that the initial state of the view does not have default/residual values displayed.

<Warning>It is mandatory for views implementing the FXView protocol to provide the intrinsic content size.</Warning>

```swift theme={"system"}
override var intrinsicContentSize: CGSize {
    return CGSize(width: UIScreen.main.bounds.width, height: 100)
}
```

#### SwiftUI Custom components

Custom SwiftUI components can be provided as type-erased views.

`FXCustomComponentViewModel` is a class implementing the `ObservableObject` protocol. It is used for managing the state of custom SwiftUI views.
It has two published properties, for data and actions. It also includes a `saveData` dictionary and a `validate` closure used for submitting and validating data from the custom components.

```swift theme={"system"}
    @Published public var data: Any?
    @Published public var actions: [ProcessActionModel] = []
    public var saveData: [String: Any]?
    public var validate: (() -> Bool)?
```

Example

```swift theme={"system"}
struct SampleView: View {
    
    @ObservedObject var viewModel: FXCustomComponentViewModel
            
    var body: some View {
        Text("Lorem")
    }
}
```

### Validating SwiftUI Custom Components

A SwiftUI Custom Component can validate and submit data from a custom component, when executing an action from a FlowX.AI UI Component.

* `public var saveData: [String: Any]?`
  Used for setting data to be submitted from the custom component.

* `public var validate: (() -> Bool)?`
  Used for validating the custom component data before executing the action.

#### Sample

```swift theme={"system"}
struct MyCustomView: View {

    @ObservedObject var viewModel: FXCustomComponentViewModel

    var body: some View {
        VStack {
            ...
        }
        .onAppear {
            viewModel.saveData = ["customKey": "customValue"]
            viewModel.validate = {
                return true
            }
        }
        .frame(height: 200)
    }
}
```

### Custom header view for Stepper navigation

The container application can provide a custom view that will be used as the stepper navigation header, using the `FXDataSource` protocol method `viewForStepperHeader`.
The method has a parameter, which provides the data needed for populating the view's UI.

```swift theme={"system"}
public struct StepViewModel {
    // title for the current step; optional
    public var stepTitle: String?
    // title for the current substep, if there is a stepper in stepper configured; optional
    public var substepTitle: String?
    // 1-based index of the current step
    public var step: Int
    // total number of steps
    public var totalSteps: Int
    // 1-based index of the current substep, if there is a stepper in stepper configured; optional
    public var substep: Int?
    // total number of substeps in the current step, if there is a stepper in stepper configured; optional
    public var totalSubsteps: Int?
}
```

#### Sample

```swift theme={"system"}
struct CustomStepperHeaderView: View {
    
    let viewModel: StepViewModel
            
    var body: some View {
        VStack(spacing: 16) {
            ProgressView(value: Float(stepViewModel.step) / Float(stepViewModel.totalSteps))
                .foregroundStyle(Color.blue)
            if let stepTitle = stepViewModel.stepTitle {
                Text(stepTitle)
            }
            if let substepTitle = stepViewModel.substepTitle {
                Text(substepTitle)
            }
        }
        .background(Color.white)
        .shadow(radius: 10)
    }
}
```

### How to run an action from a custom component

The custom components which the container app provides will contain FlowX actions to be executed. To run an action you need to call the following method:

```swift theme={"system"}
public func runAction(action: ProcessActionModel,
                      params: [String: Any]? = nil)
```

`action` - the `ProcessActionModel` action object

`params` - the parameters for the action

### How to run an upload action from a custom component

```swift theme={"system"}
public func runUploadAction(action: ProcessActionModel,
                            image: UIImage)
```

`action` - the `ProcessActionModel` action object

`image` - the image to upload

```swift theme={"system"}
public func runUploadAction(action: ProcessActionModel,
                            fileURL: URL)
```

`action` - the `ProcessActionModel` action object

`fileURL` - the local URL of the file

### Getting a substitution tag value by key

```swift theme={"system"}
public func getTag(withKey key: String) -> String?
```

All substitution tags will be retrieved by the SDK before starting the first process and will be stored in memory.&#x20;

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag using the method above, providing the key.

### Getting a media item url by key

```swift theme={"system"}
public func getMediaItemURL(withKey key: String) -> String?
```

All media items will be retrieved by the SDK before starting the first process and will be stored in memory.

Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url using the method above, providing the key.

### Getting enumeration values

The SDK provides two methods for fetching enumeration values, an async/await version and a callback version.

```swift theme={"system"}
public func getEnumeration(name: String,
                           parentName: String?) async -> [EnumerationItem]?
```

```swift theme={"system"}
public func getEnumeration(name: String,
                           parentName: String?,
                           completion: (([EnumerationItem]?) -> Void)?)
```

* `name` - the name of the enumeration to retrieve

* `parentName` - the parent enumeration name, if the enumeration is a child. Pass `nil` for root enumerations.

* `completion` - a closure called with the array of enumeration items, or `nil` if not found (callback version only)

The method first checks the local cache and returns cached items if available. If not cached, it fetches the enumeration from the server.

#### EnumerationItem

```swift theme={"system"}
public struct EnumerationItem: Codable {
    public var type: String?
    public var order: Int?
    public var childContentDescription: EnumerationChildContentDescription?
    public var code: String?
    public var content: String?
}

public struct EnumerationChildContentDescription: Codable {
    public var name: String?
}
```

#### Sample

```swift theme={"system"}
// Using async/await
let items = await FlowX.sharedInstance.getEnumeration(name: "cities",
                                                      parentName: "countries")

// Using completion handler
FlowX.sharedInstance.getEnumeration(name: "cities",
                                    parentName: "countries") { items in
    guard let items = items else { return }
    // use enumeration items
}
```

### Collecting analytics events

To collect analytics events from the SDK, the `collect(event: AnalyticsEvent)` func of the `FXDataSource` protocol needs to be implemented.

The func will be called by the SDK each time a screen or an action analytics event occurs.

The type of the event and relevant metadata are included in the func parameter `event` which is a `AnalyticsEvent` enum case.

```Swift theme={"system"}
public enum AnalyticsEvent {
    case screen(AnalyticsScreenData)
    case action(AnalyticsActionData)
}

public struct AnalyticsScreenData {
    public var value: String
    public var customPayload: [String: Any]?
}

public struct AnalyticsActionData {
    public var value: String
    public var component: String?
    public var label: String?
    public var screen: String?
    public var customPayload: [String: Any]?
}
```

<Info>
  The value property represents the identifier set in the process definition.

  Both screen and action events include an optional `customPayload` dictionary for additional custom data configured in the process definition.

  For action type events there are some additional properties provided:

  * component - The type of component triggering the action
  * label - The label of the component, if available. (E.g. title of a button or label of a form element)
  * screen - The identifier of the screen containing the component, if set
</Info>

### Handling authorization token changes

When the access token of the auth session changes, you can update it in the renderer using the `func updateAuthorization(token: String)` method.

```swift theme={"system"}
FlowX.sharedInstance.updateAuthorization(token: accessToken)
```


# React Native SDK
Source: https://docs.flowx.ai/5.9/sdks/react-native-renderer

The React Native renderer SDK renders processes configured in the FlowX Designer inside a React Native app, using an imperative API.

## React Native project requirements

<Info>
  The library requires React Native **0.85.3+** with a `react` version that satisfies React Native's declared peer dependency (`^19.2.3` for `react-native@0.85.3`). Also requires Node **≥ 24.0.0** and npm **≥ 11.0.0**.
</Info>

| Platform                                         | Minimum                        | Notes                                                                                                            |
| ------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| iOS deployment target                            | **16.4**                       | Required by Expo SDK 56 (raised from 15.1 in 55). Set in `ios/Podfile` (`platform :ios, '16.4'`).                |
| Android `minSdkVersion`                          | **24** (Android 7.0)           | Set in `android/build.gradle`. Required by RN 0.85.                                                              |
| Android `compileSdkVersion` / `targetSdkVersion` | RN 0.85 + Expo SDK 56 defaults | Don't override unless required. Set by `react-native-gradle-plugin` / `expo-root-project` after `expo prebuild`. |

<Check>
  To install the npm libraries provided by FlowX.AI you will need access to the private FlowX.AI Nexus registry. Consult your project DevOps.
</Check>

<Warning>
  `react` must satisfy React Native's published peer dependency. For `react-native@0.85.3` this is `^19.2.3`; newer RN 0.85.x patches may shift it — check with `npm view react-native@<your-version> peerDependencies`. Installing React Native via the official template (Bare CLI) or Expo SDK 56 picks a compatible `react` automatically — don't override it with a manual pin unless you have a reason.
</Warning>

## Installation

<Tabs>
  <Tab title="Bare React Native CLI">
    For new projects, bootstrap with the official React Native template so `react` and `react-native` ship as a matched pair that satisfies the peer dependency in the Warning above:

    ```bash theme={"system"}
    npx @react-native-community/cli@latest init MyApp
    cd MyApp
    ```

    For existing projects, ensure `react` already satisfies your installed `react-native`'s declared peer (`npm view react-native@<your-version> peerDependencies`) before installing the FlowX SDK.

    Then install the FlowX SDK and peers:

    ```bash theme={"system"}
    npm install \
      @flowx/react-native-sdk@<version> \
      @flowx/react-native-ui-toolkit@<version> \
      @flowx/react-native-theme@<version> \
      @flowx/core-sdk@<version> \
      @flowx/core-theme@<version> \
      @react-navigation/native \
      @react-navigation/native-stack \
      @react-navigation/elements \
      react-native-screens \
      react-native-safe-area-context \
      react-native-svg \
      react-native-enriched-markdown \
      react-native-keyboard-controller \
      react-native-reanimated \
      react-native-worklets \
      @react-native-community/datetimepicker \
      @react-native-community/slider \
      @react-native-segmented-control/segmented-control
    ```

    <Warning>
      Replace `<version>` with the correct version corresponding to your platform version.

      To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.
    </Warning>

    Then install iOS pods:

    ```bash theme={"system"}
    cd ios && pod install && cd ..
    ```
  </Tab>

  <Tab title="Expo (SDK 56)">
    <Info>
      Expo Go is **not** supported. `react-native-keyboard-controller`, `react-native-reanimated@4`, and `react-native-worklets` require a custom native build. Use `expo-dev-client` with EAS builds or `expo prebuild`.
    </Info>

    This SDK release targets **Expo SDK 56** (stable). Older Expo SDKs are not supported.

    | Expo SDK | Status          | React Native | React                                            | Notes                                                          |
    | -------- | --------------- | ------------ | ------------------------------------------------ | -------------------------------------------------------------- |
    | **56**   | **Recommended** | 0.85.x       | 19.2.3 (Expo SDK 56 pin; satisfies RN `^19.2.3`) | Current target. New architecture is default. iOS 16.4 minimum. |
    | 55       | Not supported   | 0.83.x       | 19.2.x                                           | Use the previous `@flowx/react-native-sdk` tag.                |
    | ≤54      | Not supported   | -            | -                                                | Missing required peers (worklets autolink, React 19 baseline). |

    Align the project to Expo SDK 56:

    ```bash theme={"system"}
    npx expo install expo --fix
    ```

    `--fix` aligns `react`, `react-native`, `react-native-reanimated`, `react-native-worklets`, `react-native-safe-area-context`, `react-native-screens`, and other Expo-tracked peers to the versions validated for the installed Expo SDK. Re-run after every Expo bump.

    Install the FlowX SDK and peers with `npx expo install` (it picks Expo-validated versions and warns on incompatibilities; use it instead of `npm install`):

    ```bash theme={"system"}
    npx expo install \
      @flowx/react-native-sdk@<version> \
      @flowx/react-native-ui-toolkit@<version> \
      @flowx/react-native-theme@<version> \
      @flowx/core-sdk@<version> \
      @flowx/core-theme@<version> \
      @react-navigation/native \
      @react-navigation/native-stack \
      @react-navigation/elements \
      react-native-screens \
      react-native-safe-area-context \
      react-native-svg \
      react-native-enriched-markdown \
      react-native-keyboard-controller \
      react-native-reanimated \
      react-native-worklets \
      @react-native-community/datetimepicker \
      @react-native-community/slider \
      @react-native-segmented-control/segmented-control \
      expo-dev-client
    ```

    <Warning>
      Replace `<version>` with the correct version corresponding to your platform version.

      To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.
    </Warning>

    `react`, `react-native`, `expo`, and Expo built-ins are already in a fresh Expo project - don't reinstall them. They are pinned by Expo SDK 56's compatibility matrix; let `npx expo install --fix` resolve drift instead of pinning manually.

    ### Expo SDK 56 reference versions

    These are the versions Expo SDK 56 validates. Use `npx expo install <pkg>` to install at the right pin; do not pin manually unless you must.

    | Package                                             | Expo SDK 56 expected                                                       |
    | --------------------------------------------------- | -------------------------------------------------------------------------- |
    | `expo`                                              | `~56.0.3`                                                                  |
    | `expo-dev-client`                                   | `~56.0.14`                                                                 |
    | `expo-splash-screen`                                | `~56.0.9`                                                                  |
    | `expo-status-bar`                                   | `~56.0.4`                                                                  |
    | `babel-preset-expo`                                 | `~56.0.6`                                                                  |
    | `@expo/cli`                                         | `56.1.2`                                                                   |
    | `react`                                             | `19.2.3` (Expo SDK 56 pin; satisfies `react-native@0.85.3` peer `^19.2.3`) |
    | `react-native`                                      | `0.85.3`                                                                   |
    | `react-native-reanimated`                           | `4.3.1`                                                                    |
    | `react-native-worklets`                             | `0.8.3`                                                                    |
    | `react-native-safe-area-context`                    | `~5.7.0`                                                                   |
    | `react-native-screens`                              | `4.25.1`                                                                   |
    | `react-native-svg`                                  | `15.15.4`                                                                  |
    | `react-native-enriched-markdown`                    | `0.5.0`                                                                    |
    | `react-native-keyboard-controller`                  | `1.21.6`                                                                   |
    | `@react-native-community/datetimepicker`            | `9.1.0`                                                                    |
    | `@react-native-community/slider`                    | `5.2.0`                                                                    |
    | `@react-native-segmented-control/segmented-control` | `2.5.7`                                                                    |

    Generate native projects if your Expo project does not yet have `ios/` and `android/`:

    ```bash theme={"system"}
    npx expo prebuild --clean
    ```

    Then install iOS pods:

    ```bash theme={"system"}
    cd ios && pod install && cd ..
    ```

    `pod install` is also run automatically by `npx expo run:ios` on first launch.

    ### `app.json` plugins

    Most listed native modules autolink without an Expo config plugin. The ones that benefit from one:

    ```json theme={"system"}
    {
      "expo": {
        "plugins": [
          "expo-dev-client",
          ["react-native-keyboard-controller", {}]
        ]
      }
    }
    ```

    `react-native-reanimated` and `react-native-worklets` do not need a config plugin - the Babel plugin handles them. The `@flowx/react-native-ui-toolkit` plugin is covered in the Android Material 3 section below.

    ### Local build (no EAS)

    For development on your own machine without EAS:

    ```bash theme={"system"}
    npx expo run:ios       # builds + runs on iOS simulator or device
    npx expo run:android   # builds + runs on Android emulator or device
    ```

    First invocation runs `expo prebuild` if `ios/` or `android/` are absent, then builds via Xcode / Gradle. Requires local Xcode (iOS) and Android SDK / JDK (Android).

    Useful flags:

    ```bash theme={"system"}
    npx expo run:ios --device                 # pick a connected physical device
    npx expo run:ios --configuration Release  # release build
    npx expo run:android --variant release    # release build
    npx expo run:android --device <id>        # pick device
    ```

    After the first install, start Metro separately with the dev client:

    ```bash theme={"system"}
    npx expo start --dev-client
    ```

    The installed app on the simulator or device connects to Metro automatically.

    ### EAS Build

    Add a development profile to `eas.json` with `developmentClient: true` so the artifact ships with the dev client:

    ```json theme={"system"}
    {
      "build": {
        "development": {
          "developmentClient": true,
          "distribution": "internal"
        }
      }
    }
    ```

    Then build:

    ```bash theme={"system"}
    eas build --profile development --platform ios
    eas build --profile development --platform android
    ```

    Install the resulting artifact on device. Run `npx expo start --dev-client` to connect Metro.

    ### Metro config (monorepo)

    The default Expo Metro config works in standard projects. For monorepos with symlinked workspaces, enable symlink resolution:

    ```js theme={"system"}
    // metro.config.js
    const { getDefaultConfig } = require('expo/metro-config');
    const config = getDefaultConfig(__dirname);
    config.resolver.unstable_enableSymlinks = true;
    module.exports = config;
    ```
  </Tab>
</Tabs>

<Warning>
  Some peer dependencies require additional setup beyond `npm install`: Babel plugins, Expo config plugins, native project edits (Podfile, `styles.xml`, `AndroidManifest.xml`), or app-root providers. Check each library's install guide and apply its setup steps. Examples: `react-native-worklets` needs a Babel plugin (see below), `react-native-keyboard-controller` needs an Expo config plugin in managed projects, and `react-native-screens` / `react-native-safe-area-context` rely on autolinking plus the providers shown later in this page.
</Warning>

### Babel plugin

`react-native-worklets/plugin` **must be the last plugin** in your Babel config.

<Tabs>
  <Tab title="Expo">
    No manual config needed. `babel-preset-expo` (SDK 54+) auto-adds the worklets plugin when `react-native-worklets` is in `node_modules`.

    ```js theme={"system"}
    // babel.config.js
    module.exports = function (api) {
      api.cache(true);
      return {
        presets: ['babel-preset-expo'],
      };
    };
    ```
  </Tab>

  <Tab title="Bare RN CLI">
    ```js theme={"system"}
    // babel.config.js
    module.exports = {
      presets: ['module:@react-native/babel-preset'],
      plugins: [
        'react-native-worklets/plugin',
      ],
    };
    ```
  </Tab>
</Tabs>

### Android Material 3 date picker (opt-in)

`FlxDatePicker` on Android renders the legacy AppCompat calendar by default. To use the Material 3 picker, the host app's `AppTheme` must inherit from a Material 3 parent **and** the toolkit runtime flag `material3` must be `true`. With the flag off, the legacy calendar renders and the theme change is irrelevant.

<Tabs>
  <Tab title="Expo (managed / prebuild)">
    Register the `@flowx/react-native-ui-toolkit` config plugin. It rewrites `AppTheme` to a Material 3 parent and injects `extra.flxUiToolkit.material3 = true` into the app config, so no JS opt-in is needed:

    ```json theme={"system"}
    {
      "expo": {
        "plugins": [
          "@flowx/react-native-ui-toolkit"
        ]
      }
    }
    ```

    Then run `npx expo prebuild --clean --platform android`.
  </Tab>

  <Tab title="Bare React Native CLI">
    Two steps.

    **Step 1.** Edit `android/app/src/main/res/values/styles.xml`:

    ```xml theme={"system"}
    <!-- Before -->
    <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
      <!-- ... -->
    </style>

    <!-- After -->
    <style name="AppTheme" parent="Theme.Material3.DayNight.NoActionBar">
      <!-- ... -->
    </style>
    ```

    **Step 2.** Opt in from JS. Pick one:

    Option A. `FlxThemeProvider` prop:

    ```tsx theme={"system"}
    import { FlxThemeProvider } from '@flowx/react-native-ui-toolkit'

    export default function App() {
      return (
        <FlxThemeProvider material3>
          {/* ... */}
        </FlxThemeProvider>
      )
    }
    ```

    Option B. Explicit call at app bootstrap (top of `index.js`):

    ```ts theme={"system"}
    import { configureFlxUiToolkit } from '@flowx/react-native-ui-toolkit'

    configureFlxUiToolkit({ material3: true })
    ```
  </Tab>
</Tabs>

<Info>
  No Gradle changes required. `com.google.android.material:material` is already on the classpath via `androidx.appcompat`. Skip both steps and `FlxDatePicker` keeps rendering the legacy calendar with no crash.
</Info>

## App-root providers

The renderer expects safe-area and keyboard providers above it in the tree:

```tsx theme={"system"}
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { KeyboardProvider } from 'react-native-keyboard-controller'

export default function App() {
  return (
    <SafeAreaProvider>
      <KeyboardProvider>
        {/* FlowX process view goes here */}
      </KeyboardProvider>
    </SafeAreaProvider>
  )
}
```

<Info>
  The SDK mounts its own `NavigationContainer` internally, wrapped in `NavigationIndependentTree`. A host `NavigationContainer` is **not** required. If your app already uses `@react-navigation/native`, keep its `NavigationContainer` at the root. The SDK's internal navigator stays isolated from it.
</Info>

## Authorization

<Info>
  The client app implements the authorization flow (using the **OpenID Connect** standard). The SDK expects a bearer token to be set via `FlowX.setAccessToken(token)` before starting a process.
</Info>

```ts theme={"system"}
import { FlowX } from '@flowx/react-native-sdk'

FlowX.setAccessToken(accessToken)
```

Call `setAccessToken` again whenever the token is refreshed.

## Configuring the SDK

`FlowX.configure(cfg)` sets global SDK config. Call it once at app bootstrap, before starting any process.

```ts theme={"system"}
import { FlowX } from '@flowx/react-native-sdk'

FlowX.configure({
  baseURL: 'https://yourDomain.dev',
  processApiPath: 'onboarding',
  organizationId: '10000001-0001-0001-8001-100000000001',
  language: 'en',
  locale: 'en-US',
  staticAssetsPath: 'https://yourDomain.dev/static',
  isDraft: false,
})
```

### `FlxConfig` parameters

| Name               | Description                                                                                                                                                                                                                            | Type      | Mandatory | Default |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------- | ------- |
| `baseURL`          | Base API URL                                                                                                                                                                                                                           | `string`  | true      | -       |
| `processApiPath`   | Process subpath                                                                                                                                                                                                                        | `string`  | true      | -       |
| `organizationId`   | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). | `string`  | true      | -       |
| `language`         | Language used to localize enumerations                                                                                                                                                                                                 | `string`  | false     | -       |
| `locale`           | Locale used to format dates, currency, numbers                                                                                                                                                                                         | `string`  | false     | -       |
| `staticAssetsPath` | Base path for static resources (icons, media). The SDK logs a warning if not set.                                                                                                                                                      | `string`  | false     | -       |
| `themeId`          | Theme identifier (reserved, not consumed by the RN renderer yet)                                                                                                                                                                       | `string`  | false     | -       |
| `isDraft`          | Start the process in draft state                                                                                                                                                                                                       | `boolean` | false     | `false` |

## Starting a process

`FlowX.startProcess(opts)` starts a new process instance and returns a `FlxProcessHandle`. The handle exposes a `ProcessView` component that you mount inside a screen.

```tsx theme={"system"}
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'
import { useEffect, useState } from 'react'

export function OnboardingScreen() {
  const [handle, setHandle] = useState<FlxProcessHandle | null>(null)

  useEffect(() => {
    let active = true
    let pending: FlxProcessHandle | null = null

    FlowX.startProcess({
      workspaceId: '8f52744-8403-4e8d-...',
      projectId: '111111-222222-333333-44444',
      processName: 'client_identification',
      params: { firstName: 'John', lastName: 'Smith' },
    }).then((h) => {
      if (!active) {
        h.dispose()
        return
      }
      pending = h
      setHandle(h)
    })

    return () => {
      active = false
      pending?.dispose()
    }
  }, [])

  if (!handle) return null
  const { ProcessView } = handle
  return <ProcessView />
}
```

### `StartProcessOptions`

| Name               | Description                                                                                                  | Type                                    | Mandatory | Example                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------------- | --------- | ------------------------- |
| `workspaceId`      | Workspace identifier                                                                                         | `string`                                | true      | `'8f52744-8403-4e8d-...'` |
| `projectId`        | FlowX Project UUID. Get it from **FlowX Dashboard → Projects → copy UUID from the project actions popover**. | `string`                                | true      | `'111111-222222-...'`     |
| `appVersionId`     | Pin to a specific app version                                                                                | `string`                                | false     | -                         |
| `processName`      | Identifies the process to start                                                                              | `string`                                | true      | `'client_identification'` |
| `params`           | Data passed when starting the process                                                                        | `Record<string, unknown>`               | false     | `{ firstName: 'John' }`   |
| `resourceId`       | Resource identifier                                                                                          | `string`                                | false     | -                         |
| `buildId`          | Pinned build identifier                                                                                      | `string`                                | false     | -                         |
| `isModal`          | Render the process as a modal screen                                                                         | `boolean`                               | false     | `false`                   |
| `onClose`          | Called when the process view is closed                                                                       | `() => void`                            | false     | -                         |
| `onProcessStarted` | Called when the main process instance is started. Receives the new `processInstanceUuid`.                    | `(processInstanceUuid: string) => void` | false     | -                         |

### Getting the process identifier

Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as `processName`.

## Continuing a process

`FlowX.continueProcess(opts)` resumes an existing process instance by its UUID.

```tsx theme={"system"}
import { FlowX } from '@flowx/react-native-sdk'

const handle = await FlowX.continueProcess({
  processInstanceUuid: 'a3f1c2d4-...',
})
```

### `ContinueProcessOptions`

| Name                  | Description                            | Type         | Mandatory |
| --------------------- | -------------------------------------- | ------------ | --------- |
| `processInstanceUuid` | UUID of the process instance to resume | `string`     | true      |
| `isModal`             | Render the process as a modal screen   | `boolean`    | false     |
| `onClose`             | Called when the process view is closed | `() => void` | false     |

## The process handle

Both `startProcess` and `continueProcess` resolve to a `FlxProcessHandle`:

```typescript theme={"system"}
interface FlxProcessHandle {
  processInstanceUuid: string
  ProcessView: ComponentType
  dispose(): void
}
```

| Member                | Description                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| `processInstanceUuid` | UUID of the running process instance                                                                |
| `ProcessView`         | React component that renders the process screens. Mount it inside a screen in your navigation tree. |
| `dispose()`           | Tears down the running process and resets SDK stores. Call when the screen unmounts.                |

<Warning>
  Always call `handle.dispose()` when the host screen unmounts. Skipping it leaks SDK store state into the next process.
</Warning>

## Full example

```tsx theme={"system"}
import { useEffect, useState } from 'react'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { KeyboardProvider } from 'react-native-keyboard-controller'
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'

FlowX.configure({
  baseURL: 'https://yourDomain.dev',
  processApiPath: 'onboarding',
  organizationId: '10000001-0001-0001-8001-100000000001',
  language: 'en',
  locale: 'en-US',
  staticAssetsPath: 'https://yourDomain.dev/static',
})

function OnboardingScreen({ authToken }: { authToken: string }) {
  const [handle, setHandle] = useState<FlxProcessHandle | null>(null)

  useEffect(() => {
    FlowX.setAccessToken(authToken)

    let active = true
    let pending: FlxProcessHandle | null = null

    FlowX.startProcess({
      workspaceId: '8f52744-8403-4e8d-...',
      projectId: '111111-222222-333333-44444',
      processName: 'client_identification',
      params: { firstName: 'John' },
    }).then((h) => {
      if (!active) {
        h.dispose()
        return
      }
      pending = h
      setHandle(h)
    })

    return () => {
      active = false
      pending?.dispose()
    }
  }, [authToken])

  if (!handle) return null
  const { ProcessView } = handle
  return <ProcessView />
}

export default function App({ authToken }: { authToken: string }) {
  return (
    <SafeAreaProvider>
      <KeyboardProvider>
        <OnboardingScreen authToken={authToken} />
      </KeyboardProvider>
    </SafeAreaProvider>
  )
}
```


# React SDK
Source: https://docs.flowx.ai/5.9/sdks/react-renderer

The React renderer SDK renders UI configured in the FlowX Designer as a standalone React component.

## React project requirements

Your app MUST use SCSS for styling.

<Check>
  To install the npm libraries provided by FlowX.AI you will need to obtain access to the private FlowX.AI Nexus registry. Please consult with your project DevOps.
</Check>

<Info>
  The library requires React **19**, **npm ≥ 11.0.0** and **node ≥ 24.0.0**.
</Info>

## Installing the library

Use the following command to install the **renderer** library and its required dependencies:

<Check>
  Installing `react` and `react-dom` can be skipped if you already have them installed in your project.
</Check>

```bash theme={"system"}
npm install \
  react@19 \
  react-dom@19 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

<Warning>
  Replace `<version>` with the correct version corresponding to your platform version.

  To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.
</Warning>

## Initial setup

Once installed, `FlxProcessRenderer` will be imported from the `@flowx/react-sdk` package.

### Theming

Component theming is done through the `@flowx/react-theme` library. The theme id is a required input for the renderer SDK component and is used to fetch the theme configuration. The id can be obtained from the admin panel in the themes section.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/2024-04-08%2013.45.10.gif)
</Frame>

### Authorization

<Info>
  It's the responsibility of the client app to implement the authorization flow (using the **OpenID Connect** standard). The renderer SDK will expect the authToken to be passed to the `FlxProcessRenderer` as an input.
</Info>

```tsx theme={"system"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        apiUrl={'your API url'}
        authToken={...}
        processName={...}
        processStartData={...}
        workspaceId={...}
        processApiPath={...}
        themeId="12345678-1234-1234-1234-123456789012"
        staticAssetsPath={...}
        locale="en-US"
        language="en"
        projectInfo={{
            projectId: ...
        }}
        organizationId={...}
      />
}
```

The `FlxProcessRenderer` component is required in the app module where the process will be rendered. The component accepts a props where you can pass extra config info, register a **custom component** or **custom validators**.

**Custom components** will be referenced by name when creating the template config for a user task.

**Custom validators** will be referenced by name (`customValidator`) in the template config panel in the validators section of each generated form field.

```tsx theme={"system"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        apiUrl={'your API url'}
        language={...}
        authToken={...}
        processName={...}
        processStartData={...}
        workspaceId={...}
        processApiPath={...}
        themeId="12345678-1234-1234-1234-123456789012"
        components={{ MyCustomComponentIdentifier: MyCustomComponent }}
        validators={{ customValidator: (...params: string[]) => (v: string) => v === '4.5'}}
        staticAssetsPath={...}
        locale="en-US"
        language="en"
        projectInfo={{
            projectId: ...
        }}
        organizationId={...}
      />
}

```

The entry point of the library is the `<FlxProcessRenderer />` component. A list of accepted inputs is found below:

```tsx theme={"system"}
<FlxProcessRenderer
    apiUrl={apiUrl}
    language={language}
    authToken={authToken}
    processName={processName}
    processStartData={processStartData}
    workspaceId={workspaceId}
    processApiPath={apiPath}
    themeId={themeId}
    components={customComponents}
    validators={validators}
    staticAssetsPath={assetsPath}
    locale={locale}
    language={language}
    projectInfo={projectInfo}
    organizationId={organizationId}
    />
```

**Parameters**:

| Name                   | Description                                                                                                                                                                                                                            | Type                                    | Mandatory | Default value | Example                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------- | ------------- | ---------------------------------------------- |
| `apiUrl`               | Your base url                                                                                                                                                                                                                          | `string`                                | true      | -             | `https://yourDomain.dev`                       |
| `processApiPath`       | Process subpath                                                                                                                                                                                                                        | `string`                                | true      | -             | `onboarding`                                   |
| `authToken`            | Authorization token                                                                                                                                                                                                                    | `string`                                | true      | -             | `'eyJhbGciOiJSUzI1NiIsIn....'`                 |
| `themeId`              | Theme id used to style the process. Can be obtained from the themes section in the admin                                                                                                                                               | `string`                                | true      | -             | `'123-456-789'`                                |
| `processName`          | Identifies a process                                                                                                                                                                                                                   | `string`                                | true      | -             | `client_identification`                        |
| `processStartData`     | Data required to start the process                                                                                                                                                                                                     | `json`                                  | true      | -             | `{ "firstName": "John", "lastName": "Smith"}`  |
| `workspaceId`          | Workspace id                                                                                                                                                                                                                           | `string`                                | true      | -             | `'8f52744-8403-4e8d....'`                      |
| `projectInfo`          | Defines which FlowX Project will be run inside the process renderer. Shape: `{ projectId: string, appVersionId?: string }`                                                                                                             | `object`                                | true      | -             | `{ "projectId": "111111-222222-333333-44444"}` |
| `organizationId`       | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). | `string`                                | true      | -             | `'10000001-0001-0001-8001-100000000001'`       |
| `language`             | Language used to localize the enumerations inside the app.                                                                                                                                                                             | `string`                                | false     | `ro`          | -                                              |
| `locale`               | Locale used to apply date, currency and number formatting to data model values                                                                                                                                                         | `string`                                | false     | `ro-RO`       | `"en-US"`                                      |
| `isDraft`              | When true, starts the process in draft state                                                                                                                                                                                           | `boolean`                               | false     | `false`       | -                                              |
| `legacyHttpVersion`    | Use legacy HTTP API version                                                                                                                                                                                                            | `boolean`                               | false     | `false`       | -                                              |
| `buildId`              | Pinned build identifier                                                                                                                                                                                                                | `string`                                | false     | -             | -                                              |
| `cache`                | Enable caching                                                                                                                                                                                                                         | `boolean`                               | false     | -             | -                                              |
| `requestInterceptors`  | Axios request interceptors applied to all SDK HTTP calls                                                                                                                                                                               | `HttpRequestInterceptor[]`              | false     | -             | -                                              |
| `responseInterceptors` | Axios response interceptors applied to all SDK HTTP calls                                                                                                                                                                              | `HttpResponseInterceptor[]`             | false     | -             | -                                              |
| `onProcessEnded`       | Callback fired when the main process reaches a terminal state                                                                                                                                                                          | `() => void`                            | false     | -             | -                                              |
| `onProcessStarted`     | Callback fired when the main process instance is started. Receives the new `processInstanceUuid`.                                                                                                                                      | `(processInstanceUuid: string) => void` | false     | -             | -                                              |
| `customLoader`         | Custom loader components for different loading scenarios.                                                                                                                                                                              | `object`                                | false     | -             | `{ startProcess: <LoaderComponent /> }`        |

#### `projectInfo` shape

```typescript theme={"system"}
projectInfo: {
  projectId: string                    // required
  appVersionId?: string                // pin a specific app version
}
```

#### Interceptor types

```typescript theme={"system"}
type HttpRequestInterceptor = {
  onFulfilled?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>
  onRejected?: (error: any) => any
}

type HttpResponseInterceptor = {
  onFulfilled?: (response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>
  onRejected?: (error: any) => any
}
```

### Analytics

<Info>
  The SDK provides a mechanism for collecting analytics events through a unified `CustomEvent` system. These events can be used to track screens and action events.
</Info>

To use analytics features, make sure you've imported the necessary SDK module:

```ts theme={"system"}
import {
   ANALYTICS_EVENTS,
   AnalyticsData,
   pushAnalyticsData,
} from '@flowx/core-sdk';
```

#### Emitting analytics events

Analytics events are dispatched using the `pushAnalyticsData(payload: AnalyticsData)` method. The SDK defines two event types:

```ts theme={"system"}
enum ANALYTICS_EVENTS {
  SCREEN = 'SCREEN',
  ACTION = 'ACTION',
}
```

Each analytics event should be an object of type AnalyticsData:

```ts theme={"system"}
type AnalyticsData = {
  type: ANALYTICS_EVENTS;
  value: string;
  screen?: string;
  component?: string;
  label?: string;
  customPayload?: object;
}
```

<Info>
  The value property represents the identifier set in the process definition.

  For ACTION type events there are some additional properties provided:

  * component - The type of component triggering the action
  * label - The label of the component
  * screen - The identifier of the screen containing the component, if set
</Info>

#### Listening for analytics events

You can subscribe to analytics events using the standard CustomEvent API:

```ts theme={"system"}
const analyticsListener = (event: CustomEvent<AnalyticsData>) => {
  console.log('Received flowx:analytics event:', event.detail);
}

useEffect(() => {
  document.addEventListener('flowx:analytics', analyticsListener)

  return () => {
    document.removeEventListener('flowx:analytics', analyticsListener)
  }
}, [])
```

<Check> Ensure that you remove the event listener on component destruction to avoid memory leaks. </Check>

#### Custom payload

This allows you to capture and send custom data alongside standard analytics events.

When analytics custom payload is configured in FlowX Designer, the renderer automatically processes variable substitution and includes the resulting data in analytics events.

<Steps>
  <Step title="Receive custom payload configuration">
    The renderer receives the analytics configuration as a JSON string with variable placeholders:

    ```json theme={"system"}
    "analyticsCustomPayload": "{\n \"name\": ${app.input}\n}"
    ```
  </Step>

  <Step title="Process variable substitution">
    The SDK replaces variables with actual values from the process data store:

    <CodeGroup>
      ```json Template theme={"system"}
      {
          "name": "${app.input}",
          "client": "${app.client}",
          "amount": "${app.amount}"
      }
      ```

      ```json Result theme={"system"}
      {
          "name": "john",
          "client": { "id": "123", "name": "John Doe" },
          "amount": 1500
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Add to analytics event">
    The processed payload is included in the analytics event under the `customPayload` property:

    ```typescript theme={"system"}
    // Analytics event structure with custom payload
    {
        type: 'ACTION', // or 'SCREEN'
        info: {
            value: 'Save personal data',
            screen: 'Personal Data',
            component: 'BUTTON',
            label: 'Save',
            customPayload: {
                name: "john",
                client: { id: "123", name: "John Doe" },
                amount: 1500
            }
        }
    }
    ```
  </Step>
</Steps>

## Starting a process

### Prerequisites

* **Process Name**: You need to know the name of the process you want to start. This name is used to identify the process in the system.

* **FlowX Project UUID**: You need the UUID of the FlowX Project that contains the process you want to start. This UUID is used to identify the project in the system.

* **Locale**: You can specify the locale of the process to apply date, currency, and number formatting to data model values.

* **Language**: You can specify the language used to localize the enumerations inside the app.

### Getting the project UUID

The project UUID can be obtained from the FlowX Dashboard. Navigate to the Projects section and select the project you want to start a process in. The UUID can be copied from the project actions popover.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/copy_uuid_application.png)

### Getting the process identifier

Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as `processName`.

### Initializing the process renderer

To start a process, you need to initialize the `FlxProcessRenderer` component in your app. The component accepts various props that define the process to start, the theme to use, and other configuration options.

```tsx theme={"system"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        {...props}
        locale="en-US"
        language="en"
        processName={processName}
        projectInfo={{ projectId }}
      />
}
```

## Custom components

Custom components receive an `input` prop of type `FlxCustomComponentData` and are registered through the `components` parameter of `<FlxProcessRenderer />`.

<Warning>
  The object keys passed in the `components` prop **MUST** match the custom component names defined in the FlowX process.
</Warning>

<Check>
  Process data mapped through `inputKeys` is available on `input.data`. The value is whatever lives at the configured path in the process model - it can be an object or a primitive.
</Check>

<Check>
  Process actions are available on `input.actionsFn`, keyed by action name.
</Check>

```typescript theme={"system"}
interface FlxCustomComponentData {
  data: any                                                          // value at the configured inputKey path - object or primitive
  actions: ProcessAction[]                                           // metadata for each bound action
  actionsFn: Record<string, (params?: any) => Observable<any>>      // call to trigger a process action; returns an Observable
}
```

Each custom component receives four props:

| Prop                 | Type                                              | Description                                                                                                                       |
| -------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `input`              | `FlxCustomComponentData`                          | Process data and bound actions                                                                                                    |
| `registerValidation` | `(fn: () => boolean \| Promise<boolean>) => void` | Register a validation function. The SDK calls it when the user submits the process step. Return `true` to pass, `false` to block. |
| `saveData`           | `(fn: () => Record<string, unknown>) => void`     | Register a data extractor. The SDK calls it on submit to collect values to write back to the process model.                       |
| `isSubmitted`        | `boolean`                                         | `true` after the first submit attempt - use to show validation errors.                                                            |

```tsx theme={"system"}
export const MyCustomComponent = ({
  input,
  registerValidation,
  saveData,
  isSubmitted,
}: {
  input: FlxCustomComponentData
  registerValidation: (fn: () => boolean | Promise<boolean>) => void
  saveData: (fn: () => Record<string, unknown>) => void
  isSubmitted: boolean
}) => {
  const { data, actionsFn } = input
  // data - the value mapped via inputKeys; e.g. { firstName: 'John' } or a primitive
  // actionsFn['save_order']() - triggers the 'save_order' process action
}
```

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.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom.png)

The properties that can be configured are as follows:

* **Identifier** - This enables the custom component to be displayed within the component hierarchy and determines the actions available for the component.
* **Input keys** - These are used to specify the pathway to the process data that components will utilize to receive their information.
* [**Event Handlers**](../docs/building-blocks/ui-designer/event-handlers) - actions defined here will be made available to the custom component

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom_settings.png#center)
</Frame>

### Prerequisites (before creation)

* **React Knowledge**: You should have a good understanding of React, as custom components are created and imported using React.

* **Development Environment**: Set up a development environment for React development, including Node.js and npm (Node Package Manager).

* **Component Identifier**: You need a unique identifier for your custom component. This identifier is used for referencing the component within the app.

### Creating a custom component

To create a Custom Component in React, follow these steps:

1. Create a new React component.
2. Implement the necessary HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior of your custom component.

### Importing the component

After creating the Custom Component, you need to import it into your app.

In your `<FlxProcessRenderer />` component, add the following property:

```tsx theme={"system"}
<FlxProcessRenderer
  {...otherProps}
  components={{ MyCustomComponentIdentifier: MyCustomComponent }}
/>
```

### Using the custom component

Once your Custom Component is declared, you can use it for configuration within your app.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_component.gif)

### Data input and actions

The Custom Component accepts input data from processes and can also include actions extracted from a process. These inputs and actions allow you to configure and interact with the component dynamically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_input_data.png)

### Extracting data from processes

There are multiple ways to extract data from processes to use within your Custom Component. You can utilize the data provided by the process or map actions from the BPMN process to React actions within your component.

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_loader_input.png)
</Frame>

<Warning>
  Make sure that the React actions that you declare match the names of the process actions.
</Warning>

### Styling with CSS

To apply CSS classes to UI elements within your Custom Component, you first need to identify the UI element identifiers within your component's HTML structure. Once identified, you can apply defined CSS classes to style these elements as desired.

Example:

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/Screenshot%202023-10-10%20at%2012.29.51.png)
</Frame>

### Additional considerations

* **Naming Conventions**: Be consistent with naming conventions for components, identifiers, and actions. Ensure that React action names match the names of process actions.

* **Component Hierarchy**: Understand how the component fits into the overall component hierarchy of your app. This will help determine where the component is displayed and what actions are available for it.

* **Documentation and Testing**: Document your custom component thoroughly for future reference. Additionally, testing is crucial to ensure that the component behaves as expected in various scenarios.

* **Security**: If your custom component interacts with sensitive data or performs critical actions, consider security measures to protect the app from potential vulnerabilities.

* **Integration with FlowX Designer**: Ensure that your custom component integrates with FlowX Designer, as it is part of the app's process modeling capabilities.

## Custom validators

You may also define custom validators in your FlowX processes and pass their implementation through the `validators` prop of the `<FlxProcessRenderer />` component.

The validators are processed through a custom validation layer backed by [Valtio](https://github.com/pmndrs/valtio) state management, taking into account how the error messages are defined in your process.

A validator must have the following type:

```typescript theme={"system"}
const customValidator = (...params: string[]) => (v: any) => boolean | Promise<boolean>
```

<Warning>
  The object keys passed in the `validators` prop **MUST** match the custom validator names defined in the FlowX process.
</Warning>

## Process end handling

The SDK provides a mechanism for container applications to handle process completion events through the `onProcessEnded` callback. This allows you to implement custom logic when a main process reaches an end state, such as redirecting users or triggering cleanup operations.

The `onProcessEnded` callback is triggered when the **main process** (not subprocesses) reaches any terminal state:

* `FINISHED` - Process completed successfully
* `FAILED` - Process encountered an error
* `ABORTED` - Process was manually terminated
* Other terminal states

<Info>
  Only the main process triggers this callback. Subprocess completions do not trigger the callback to avoid unnecessary interruptions during complex process flows.
</Info>

### Implementation

To handle process end events, pass a function to the `onProcessEnded` prop of the `<FlxProcessRenderer />` component:

```tsx theme={"system"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
  const handleProcessEnd = () => {
    // Your custom logic here
    console.log('Process has ended');
    
    // Example: Redirect to home page
    window.location.href = '/dashboard';
  };

  return (
    <FlxProcessRenderer
      {...otherProps}
      onProcessEnded={handleProcessEnd}
    />
  );
}
```

## Custom loader

The SDK provides a mechanism for container applications to customize the loader UI displayed during process execution. This allows you to replace the default FlowX loader with your own custom implementation based on different loading scenarios.

### Configuration

To configure custom loaders, pass them through the `customLoader` prop of the `<FlxProcessRenderer />` component:

```tsx theme={"system"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

// Define your custom loader components
const StartProcessLoader = () => (
  <div className="custom-start-loader">
    <div className="spinner" />
    <p>Starting process...</p>
  </div>
);

const SpecificActionLoader = () => (
  <div className="custom-specific-action-loader">
    <div className="spinner" />
    <p>Executing specific action...</p>
  </div>
);

// Register the custom loaders in your component
export function MyFlxContainer() {
  return (
    <FlxProcessRenderer
      {...otherProps}
      customLoader={{
        startProcess: <StartProcessLoader />,
        // reloadProcess: <ReloadProcessLoader />,
        // defaultAction: <DefaultActionLoader />,
        // defaultUpload: <DefaultUploadLoader />,
        actions: {
          action1: <SpecificActionLoader />,
          // action2: <SaveDataLoader />,
        },
      }}
    />
  );
}
```

### API specification

The `customLoader` prop accepts an object of type `CustomLoader`:

```typescript theme={"system"}
type CustomLoader = {
  actions?: Record<string, ReactNode>
  startProcess?: ReactNode
  reloadProcess?: ReactNode
  defaultAction?: ReactNode
  defaultUpload?: ReactNode
}
```

#### Loader types

* **`startProcess`** - Displayed when starting or resuming a process
* **`reloadProcess`** - Displayed when reloading a process
* **`defaultAction`** - Default loader for actions when `loaderType` is `'action'`. Used when no specific action loader is found in the `actions` record
* **`defaultUpload`** - Default loader for file uploads when `loaderType` is `'upload'`
* **`actions`** - Record mapping specific action identifiers to custom loaders. When an action is executed, the SDK will first check for a matching entry in this record before falling back to `defaultAction`

### Fallback behavior

<Info>
  If no custom loader is provided for a specific type, the SDK will automatically fall back to the built-in FlowX loader. This ensures your app continues to function even with partial custom loader configuration.
</Info>

<Tip>
  You can use any React components, including those with animations, styled components, or media assets, to create rich loading experiences that match your app's design system.
</Tip>

## Chat component

To use the `FlxChatRenderer` component, import the module in your project:

```tsx theme={"system"}
import { FlxChatRenderer } from '@flowx/react-sdk';
```

#### Usage

Include the component in your template:

```tsx theme={"system"}
  <FlxChatRenderer
    apiUrl={baseUrl}
    authToken={accessToken}
    staticAssetsPath={staticAssetsPath}
    language={language}
    locale={locale}
    themeId={themeId}
    projectId={projectId}
    workspaceId={workspaceId}
    source={source}
    chatConfig={chatConfig}
    cache={cache}
  />
```

Parameters:

| Name                | Description                                   | Type      | Mandatory | Example                           |
| ------------------- | --------------------------------------------- | --------- | --------- | --------------------------------- |
| `apiUrl`            | Your base API URL                             | `string`  | ✅         | `https://yourDomain.dev`          |
| `authToken`         | Authorization token                           | `string`  | ✅         | (retrieved from auth provider)    |
| `staticAssetsPath`  | Path for static resources                     | `string`  | ❌         | (set via environment)             |
| `language`          | Language used to localize the chat interface  | `string`  | ❌         | `en`                              |
| `locale`            | Locale setting for date and number formatting | `string`  | ❌         | `en-US`                           |
| `themeId`           | Theme identifier for styling                  | `string`  | ❌         | (retrieved dynamically)           |
| `projectId`         | The FlowX project ID                          | `string`  | ✅         | (retrieved dynamically)           |
| `workspaceId`       | The workspace ID                              | `string`  | ✅         | (retrieved dynamically)           |
| `source`            | Source object with type and id                | `object`  | ✅         | `{ type: 'WORKFLOW', id: '...' }` |
| `chatConfig`        | Chat configuration object                     | `object`  | ❌         | `{ welcomeMessage: '...', ... }`  |
| `cache`             | Enable caching for chat responses             | `boolean` | ❌         | `true`                            |
| `buildId`           | Pinned build identifier                       | `string`  | ❌         | (retrieved dynamically)           |
| `legacyHttpVersion` | Use legacy HTTP API version                   | `boolean` | ❌         | -                                 |

#### chatConfig parameters

The `chatConfig` object accepts the following properties:

| Name               | Description                                  | Type      | Default value            |
| ------------------ | -------------------------------------------- | --------- | ------------------------ |
| `welcomeMessage`   | Message displayed when chat is first opened  | `string`  | `'Welcome to the chat!'` |
| `thinkingMessage`  | Message displayed while waiting for response | `string`  | `'Thinking...'`          |
| `title`            | Chat window title                            | `string`  | `'Chat'`                 |
| `subtitle`         | Chat window subtitle                         | `string`  | `'Chat subtitle'`        |
| `showChatIcon`     | Whether to display the chat icon             | `boolean` | `true`                   |
| `showSeparator`    | Whether to show separator between messages   | `boolean` | `true`                   |
| `newChatLabel`     | Label for the new chat button                | `string`  | `'New chat'`             |
| `inputPlaceholder` | Placeholder text for the message input field | `string`  | `'Enter your message'`   |
| `maxInputRows`     | Maximum number of rows for the input field   | `number`  | `10`                     |
| `historyTitle`     | Title displayed on the chat history panel    | `string`  | -                        |
| `errorMessage`     | Message shown when an error occurs           | `string`  | -                        |
| `canRegenerate`    | Show a regenerate button on responses        | `boolean` | -                        |
| `regenerateLabel`  | Label for the regenerate button              | `string`  | -                        |

## Task management component

To use the `FlxTaskManager` component, import the module in your project:

```tsx theme={"system"}
import { FlxTaskManager } from '@flowx/react-sdk';
```

#### Usage

Include the component in your template:

```tsx theme={"system"}
  <FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    themeId={themeId}
    language={language}
    locale={locale}
    staticAssetsPath={staticAssetsPath}
    buildId={buildId}
  />
```

Parameters:

| Name                | Description                                                               | Type                       | Mandatory | Example                        |
| ------------------- | ------------------------------------------------------------------------- | -------------------------- | --------- | ------------------------------ |
| `apiUrl`            | Endpoint where the tasks are available                                    | `string`                   | ✅         | `https://yourDomain.dev/tasks` |
| `authToken`         | Authorization token                                                       | `string`                   | ✅         | (retrieved from local storage) |
| `appInfo`           | App information object. Shape: `{ appId: string, appVersionId?: string }` | `object`                   | ✅         | `{ appId: "app-123" }`         |
| `viewId`            | The view configuration identifier                                         | `string`                   | ✅         | (retrieved dynamically)        |
| `workspaceId`       | The workspace ID                                                          | `string`                   | ✅         | (retrieved dynamically)        |
| `themeId`           | The theme identifier                                                      | `string`                   | ❌         | (retrieved dynamically)        |
| `language`          | The selected language                                                     | `string`                   | ❌         | (retrieved dynamically)        |
| `locale`            | The localization setting                                                  | `string`                   | ❌         | (retrieved dynamically)        |
| `buildId`           | The current build identifier                                              | `string`                   | ❌         | (retrieved dynamically)        |
| `staticAssetsPath`  | Path for static resources                                                 | `string`                   | ❌         | (set via environment)          |
| `stages`            | Pre-loaded enumeration stages                                             | `TaskManagerEnumeration[]` | ❌         | -                              |
| `legacyHttpVersion` | Use legacy HTTP API version                                               | `boolean`                  | ❌         | -                              |

## Task management public API

The React SDK provides a comprehensive public API for building custom task management interfaces.
This API allows you to fetch tasks, manage comments, handle task actions, and interact with task data programmatically.

### Importing the API

To use the task management public API, import the functions and types from `@flowx/react-sdk`:

```typescript theme={"system"}
import {
  // Functions
  getTaskManagerResources,
  fetchView,
  fetchViewTasks,
  fetchTaskComments,
  fetchTaskHistory,
  fetchTaskAssignees,
  updateTaskAction,
  saveComment,
  removeComment,
  updateTaskPriority,
  updateBulkTaskAction,
  fetchBulkAssignees,
  getEnumerationOptions,
  initSseConnection,
  
  // Types and Interfaces
  TaskManagerSetupOptions,
  View,
  ViewTask,
  ViewColumn,
  ViewFilter,
  TaskActions,
  TaskComment,
  TaskHistory,
  Assignees,
  TaskManagerEnumeration,
  SseConnection,
  SseEventData,
  SseMessageType,
  SseTaskMessageType,
  SseTaskEventType,
} from '@flowx/react-sdk'
```

### Initialization

Before using the task management API, you need to initialize the task manager resources. This fetches the view configuration, enumerations, and filter operators.

```typescript theme={"system"}
const { view, enumerations, filterOperators } = await getTaskManagerResources({
  apiUrl: 'https://yourDomain.dev/tasks',
  authToken: 'your-auth-token',
  appInfo: { appId: 'app-123' },
  viewId: 'view-456',
  workspaceId: 'workspace-789',
  themeId: 'theme-012', // Optional
  language: 'en', // Optional
  locale: 'en-US', // Optional
  buildId: 'build-345', // Optional
  staticAssetsPath: '/static', // Optional
})
```

**Parameters:**

| Name               | Description                             | Type                | Mandatory | Example                        |
| ------------------ | --------------------------------------- | ------------------- | --------- | ------------------------------ |
| `apiUrl`           | Endpoint where the tasks are available  | `string`            | ✅         | `https://yourDomain.dev/tasks` |
| `authToken`        | Authorization token                     | `string`            | ✅         | (retrieved from local storage) |
| `appInfo`          | App information object containing appId | `{ appId: string }` | ✅         | `{ appId: "app-123" }`         |
| `viewId`           | The view configuration identifier       | `string`            | ✅         | (retrieved dynamically)        |
| `workspaceId`      | The workspace ID                        | `string`            | ✅         | (retrieved dynamically)        |
| `themeId`          | The theme identifier                    | `string`            | ❌         | (retrieved dynamically)        |
| `language`         | The selected language                   | `string`            | ❌         | `"en"`                         |
| `locale`           | The localization setting                | `string`            | ❌         | `"en-US"`                      |
| `buildId`          | The current build identifier            | `string`            | ❌         | (retrieved dynamically)        |
| `staticAssetsPath` | Path for static resources               | `string`            | ❌         | (set via environment)          |

**Returns:** Promise resolving to an object containing:

* `view`: The view configuration object
* `enumerations`: Available enumeration options for filters
* `filterOperators`: Available filter operators for each column

### Fetching tasks

#### `fetchViewTasks`

Fetches tasks for a specific view with support for sorting, filtering, pagination, and search.

```typescript theme={"system"}
const response = await fetchViewTasks(
  sort,           // Array of sort configurations
  filters,        // Array of filter configurations
  searchTerm,     // Search string
  view,           // View object from getTaskManagerResources
  pagination,     // Pagination object { page: number, size: number }
  enumerations    // Enumerations from getTaskManagerResources
)
```

**Parameters:**

| Name           | Description                      | Type                             | Mandatory | Example                                       |
| -------------- | -------------------------------- | -------------------------------- | --------- | --------------------------------------------- |
| `sort`         | Array of sort configurations     | `ViewTasksSort[]`                | ✅         | `[{ keyName: "priority", direction: "ASC" }]` |
| `filters`      | Array of filter configurations   | `ViewTasksFilter[]`              | ✅         | See filter examples below                     |
| `searchTerm`   | Search string for task search    | `string`                         | ✅         | `"urgent"`                                    |
| `view`         | View object from initialization  | `View`                           | ✅         | (from `getTaskManagerResources`)              |
| `pagination`   | Pagination configuration         | `{ page: number, size: number }` | ✅         | `{ page: 0, size: 10 }`                       |
| `enumerations` | Enumerations from initialization | `TaskManagerEnumerations`        | ✅         | (from `getTaskManagerResources`)              |

**Returns:** Promise resolving to a paginated response containing:

* `content`: Array of `ViewTask` objects
* `totalElements`: Total number of tasks
* `totalPages`: Total number of pages
* Other pagination metadata

**Example:**

```typescript theme={"system"}
const sort = [{ keyName: 'priority', direction: 'ASC' }]
const filters = [
  {
    keyName: 'status',
    operator: 'EQUALS',
    value: ['PENDING'],
    keyType: 'enumType',
    columnType: 'status',
  },
]
const pagination = { page: 0, size: 10 }

const response = await fetchViewTasks(
  sort,
  filters,
  '', // searchTerm
  view,
  pagination,
  enumerations
)

const tasks = response.content // Array of ViewTask objects
```

#### `fetchView`

Fetches a specific view configuration by ID.

```typescript theme={"system"}
const view = await fetchView(viewId)
```

### Task details

#### `fetchTaskComments`

Fetches all comments for a specific task.

```typescript theme={"system"}
const comments = await fetchTaskComments(taskId)
```

**Parameters:**

| Name     | Description        | Type     | Mandatory | Example      |
| -------- | ------------------ | -------- | --------- | ------------ |
| `taskId` | The unique task ID | `string` | ✅         | `"task-123"` |

**Returns:** Promise resolving to an array of `TaskComment` objects.

**Example:**

```typescript theme={"system"}
const comments = await fetchTaskComments(selectedTask.id)
// Returns: [
//   {
//     commentId: "comment-1",
//     message: "This task needs attention",
//     author: { username: "john.doe", ... },
//     createdAt: "2024-01-15T10:30:00Z"
//   }
// ]
```

#### `fetchTaskHistory`

Fetches the history/audit trail for a specific task.

```typescript theme={"system"}
const history = await fetchTaskHistory(taskId)
```

**Parameters:**

| Name     | Description        | Type     | Mandatory | Example      |
| -------- | ------------------ | -------- | --------- | ------------ |
| `taskId` | The unique task ID | `string` | ✅         | `"task-123"` |

**Returns:** Promise resolving to an array of `TaskHistory` objects.

**Example:**

```typescript theme={"system"}
const history = await fetchTaskHistory(selectedTask.id)
// Returns: [
//   {
//     historyId: "history-1",
//     events: [
//       {
//         type: "STATUS_CHANGED",
//         description: "Status changed from PENDING to IN_PROGRESS"
//       }
//     ]
//   }
// ]
```

#### `fetchTaskAssignees`

Fetches available assignees for a task, with optional search filtering.

```typescript theme={"system"}
const assignees = await fetchTaskAssignees(
  taskId,
  tokenUuid,
  options
)
```

**Parameters:**

| Name        | Description                         | Type     | Mandatory | Example               |
| ----------- | ----------------------------------- | -------- | --------- | --------------------- |
| `taskId`    | The unique task ID                  | `string` | ✅         | `"task-123"`          |
| `tokenUuid` | The token UUID associated with task | `string` | ✅         | `"token-uuid-456"`    |
| `options`   | Search options                      | `object` | ❌         | `{ keyword: "john" }` |

**Returns:** Promise resolving to an array of `Assignees` objects.

**Example:**

```typescript theme={"system"}
const users = await fetchTaskAssignees(
  selectedTask.id,
  selectedTask.tokenUuid,
  { keyword: 'john' }
)
// Returns: [
//   {
//     username: "john.doe",
//     firstName: "John",
//     lastName: "Doe",
//     email: "john.doe@example.com"
//   }
// ]
```

#### `fetchBulkAssignees`

Fetches available assignees for multiple tasks in bulk.

```typescript theme={"system"}
const assignees = await fetchBulkAssignees(
  taskIds,
  options
)
```

**Parameters:**

| Name      | Description       | Type       | Mandatory | Example                |
| --------- | ----------------- | ---------- | --------- | ---------------------- |
| `taskIds` | Array of task IDs | `string[]` | ✅         | `["task-1", "task-2"]` |
| `options` | Search options    | `object`   | ❌         | `{ keyword: "john" }`  |

**Returns:** Promise resolving to an array of `Assignees` objects.

### Task actions

#### `updateTaskAction`

Executes an action on a specific task (e.g., assign, complete, cancel).

```typescript theme={"system"}
await updateTaskAction(
  action,
  taskId,
  tokenUuid,
  username
)
```

**Parameters:**

| Name        | Description                           | Type                 | Mandatory | Example              |
| ----------- | ------------------------------------- | -------------------- | --------- | -------------------- |
| `action`    | The action to execute                 | `ExecuteTaskActions` | ✅         | `TaskActions.ASSIGN` |
| `taskId`    | The unique task ID                    | `string`             | ✅         | `"task-123"`         |
| `tokenUuid` | The token UUID associated with task   | `string`             | ✅         | `"token-uuid-456"`   |
| `username`  | Username for assign action (optional) | `string`             | ❌         | `"john.doe"`         |

**Available Actions:**

* `TaskActions.ASSIGN` - Assign task to a user
* `TaskActions.COMPLETE` - Mark task as complete
* `TaskActions.CANCEL` - Cancel the task
* `TaskActions.CHANGE_PRIORITY` - Change task priority
* `TaskActions.VIEW` - View task details

**Example:**

```typescript theme={"system"}
// Assign task to a user
await updateTaskAction(
  TaskActions.ASSIGN,
  selectedTask.id,
  selectedTask.tokenUuid,
  'john.doe'
)

// Complete a task
await updateTaskAction(
  TaskActions.COMPLETE,
  selectedTask.id,
  selectedTask.tokenUuid
)
```

#### `updateBulkTaskAction`

Applies an action to multiple tasks at once.

```typescript theme={"system"}
await updateBulkTaskAction(
  action,
  taskIds,
  options
)
```

**Parameters:**

| Name      | Description           | Type                 | Mandatory | Example                    |
| --------- | --------------------- | -------------------- | --------- | -------------------------- |
| `action`  | The action to execute | `ExecuteTaskActions` | ✅         | `TaskActions.COMPLETE`     |
| `taskIds` | Array of task IDs     | `string[]`           | ✅         | `["task-1", "task-2"]`     |
| `options` | Additional options    | `object`             | ❌         | `{ username: "john.doe" }` |

**Example:**

```typescript theme={"system"}
await updateBulkTaskAction(
  TaskActions.COMPLETE,
  ['task-1', 'task-2', 'task-3']
)
```

#### `updateTaskPriority`

Updates the priority of a specific task.

```typescript theme={"system"}
await updateTaskPriority(taskId, priority)
```

**Parameters:**

| Name       | Description        | Type     | Mandatory | Example      |
| ---------- | ------------------ | -------- | --------- | ------------ |
| `taskId`   | The unique task ID | `string` | ✅         | `"task-123"` |
| `priority` | New priority value | `number` | ✅         | `5`          |

**Example:**

```typescript theme={"system"}
await updateTaskPriority(selectedTask.id, 10)
```

### Comments management

#### `saveComment`

Adds a new comment to a task.

```typescript theme={"system"}
await saveComment(taskId, commentData)
```

**Parameters:**

| Name          | Description         | Type     | Mandatory | Example                           |
| ------------- | ------------------- | -------- | --------- | --------------------------------- |
| `taskId`      | The unique task ID  | `string` | ✅         | `"task-123"`                      |
| `commentData` | Comment data object | `object` | ✅         | `{ message: "New comment text" }` |

**Example:**

```typescript theme={"system"}
await saveComment(selectedTask.id, {
  message: 'This task requires immediate attention'
})

// Refresh comments after saving
const updatedComments = await fetchTaskComments(selectedTask.id)
```

#### `removeComment`

Removes a comment from a task.

```typescript theme={"system"}
await removeComment(taskId, commentId)
```

**Parameters:**

| Name        | Description           | Type     | Mandatory | Example         |
| ----------- | --------------------- | -------- | --------- | --------------- |
| `taskId`    | The unique task ID    | `string` | ✅         | `"task-123"`    |
| `commentId` | The unique comment ID | `string` | ✅         | `"comment-456"` |

**Example:**

```typescript theme={"system"}
await removeComment(selectedTask.id, comment.commentId)
```

### Enumerations

#### `getEnumerationOptions`

Retrieves enumeration options for a specific enumeration name.

```typescript theme={"system"}
const options = await getEnumerationOptions(enumName)
```

**Parameters:**

| Name       | Description          | Type     | Mandatory | Example    |
| ---------- | -------------------- | -------- | --------- | ---------- |
| `enumName` | The enumeration name | `string` | ✅         | `"Status"` |

**Returns:** Promise resolving to an array of `TaskManagerEnumeration` objects.

### Real-time updates (SSE)

#### `initSseConnection`

Initializes a Server-Sent Events (SSE) connection for real-time task updates.

```typescript theme={"system"}
const sseConnection = initSseConnection(
  resourceId,
  eventHandler
)
```

**Parameters:**

| Name           | Description                            | Type                                                                      | Mandatory | Example           |
| -------------- | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ----------------- |
| `resourceId`   | The resource ID from the view          | `string`                                                                  | ✅         | `"resource-123"`  |
| `eventHandler` | Callback function to handle SSE events | `(event: MessageEvent&lt;string&gt;, data: SseEventData \| null) => void` | ✅         | See example below |

**Returns:** `SseConnection` object with a `close()` method.

**Example:**

```typescript theme={"system"}
const handleSseEvent = (event: MessageEvent<string>, eventData: SseEventData | null) => {
  if (event.type === SseMessageType.Data) {
    if (eventData?.eventType === SseTaskMessageType.VIEW_UPDATED) {
      // Reload tasks when view is updated
      loadTasks()
    }
  }
}

const sseConnection = initSseConnection(view.resourceId, handleSseEvent)

// Cleanup on component unmount
useEffect(() => {
  return () => {
    if (sseConnection) {
      sseConnection.close()
    }
  }
}, [])
```

**SSE Event Types:**

| Enum                 | Value          | Description                         |
| -------------------- | -------------- | ----------------------------------- |
| `SseTaskMessageType` | `VIEW_UPDATED` | View configuration has been updated |
| `SseTaskEventType`   | `TASK_UPDATED` | A task has been updated             |
| `SseTaskEventType`   | `TASK_CREATED` | A new task has been created         |

## UI Flow renderer

`FlxUiFlowRenderer` renders a full UI Flow (multi-view navigation, breadcrumbs, embedded processes, and an optional chat widget) from a single component.

```typescript theme={"system"}
import { FlxUiFlowRenderer } from '@flowx/react-sdk'
```

#### Usage

```tsx theme={"system"}
<FlxUiFlowRenderer
  apiUrl="https://yourDomain.dev"
  authToken={authToken}
  processApiPath="onboarding"
  language="en"
  locale="en-US"
  themeId="12345678-1234-1234-1234-123456789012"
  staticAssetsPath={staticAssetsPath}
  workspaceId={workspaceId}
  appInfo={{ appId: projectId }}
  organizationId={organizationId}
  isDraft={false}
  cache={true}
  uiFlowName="my-ui-flow"
  buildId={buildId}
  components={{ MyCustomComponent }}
  validators={{ myValidator: () => (v) => v !== '' }}
/>
```

#### Parameters

| Name                | Description                                                                                                                                                                                                                          | Type                            | Mandatory |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------- |
| `apiUrl`            | Base API URL                                                                                                                                                                                                                         | `string`                        | ✅         |
| `authToken`         | Authorization token                                                                                                                                                                                                                  | `string`                        | ✅         |
| `processApiPath`    | Process subpath                                                                                                                                                                                                                      | `string`                        | ✅         |
| `language`          | UI language                                                                                                                                                                                                                          | `string`                        | ❌         |
| `locale`            | Date/number formatting locale                                                                                                                                                                                                        | `string`                        | ❌         |
| `themeId`           | Theme identifier                                                                                                                                                                                                                     | `string`                        | ✅         |
| `staticAssetsPath`  | Static resources base path                                                                                                                                                                                                           | `string`                        | ✅         |
| `workspaceId`       | Workspace identifier                                                                                                                                                                                                                 | `string`                        | ✅         |
| `appInfo`           | App identity. Shape: `{ appId: string, appVersionId?: string }`                                                                                                                                                                      | `object`                        | ✅         |
| `organizationId`    | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade. See [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment) | `string`                        | ✅         |
| `isDraft`           | Render the draft version of the UI Flow                                                                                                                                                                                              | `boolean`                       | ❌         |
| `cache`             | Enable caching                                                                                                                                                                                                                       | `boolean`                       | ❌         |
| `uiFlowName`        | Name of the UI Flow to start                                                                                                                                                                                                         | `string`                        | ❌         |
| `buildId`           | Pinned build identifier                                                                                                                                                                                                              | `string`                        | ❌         |
| `startParams`       | Initial query parameters passed to the UI Flow                                                                                                                                                                                       | `Record<string, unknown>`       | ❌         |
| `components`        | Custom component registry                                                                                                                                                                                                            | `Record<string, ComponentType>` | ❌         |
| `validators`        | Custom validator registry                                                                                                                                                                                                            | `Record<string, ValidatorFn>`   | ❌         |
| `legacyHttpVersion` | Use legacy HTTP API version                                                                                                                                                                                                          | `boolean`                       | ❌         |

### Starting a UI Flow

#### Prerequisites

* **UI Flow name**: You need the name of the UI Flow to start, passed as `uiFlowName`.
* **FlowX Project UUID**: The `appInfo.appId` value, which identifies which project the UI Flow belongs to. Obtain it the same way as for processes: **FlowX Dashboard → Projects → copy UUID from the project actions popover**.
* **Process API path**: The `processApiPath` subpath used by the embedded process renderer when the UI Flow navigates into a full-screen process.

#### Getting the UI Flow name

Open the FlowX Designer and navigate to **UI Flows**. The flow name displayed in the list is the value to pass as `uiFlowName`.

#### Initializing the UI Flow renderer

Minimal working example:

```tsx theme={"system"}
import { FlxUiFlowRenderer } from '@flowx/react-sdk'

export function MyUiFlowContainer() {
  return (
    <FlxUiFlowRenderer
      apiUrl="https://yourDomain.dev"
      authToken={authToken}
      processApiPath="onboarding"
      language="en"
      locale="en-US"
      themeId={themeId}
      staticAssetsPath={staticAssetsPath}
      workspaceId={workspaceId}
      appInfo={{ appId: projectId }}
      organizationId={organizationId}
      isDraft={false}
      cache={true}
      uiFlowName={uiFlowName}
    />
  )
}
```

#### Passing initial parameters: `startParams`

Use `startParams` to inject query-string key/value pairs into the UI Flow at startup. The values are available inside the flow as URL query parameters.

```tsx theme={"system"}
<FlxUiFlowRenderer
  {...requiredProps}
  startParams={{ referralCode: 'REF123', skipIntro: true }}
/>
```

<Info>
  `startParams` is read once at initialization. To trigger a full re-initialization, change one of the primitive props such as `uiFlowName`.
</Info>

***

## Utility API

These functions and hooks are exported from `@flowx/react-sdk` and can be used independently of the renderer components.

```typescript theme={"system"}
import {
  useEnumeration,
  getEnumeration,
  getStaticAsset,
  getSubstitutionTag,
} from '@flowx/react-sdk'
```

#### `useEnumeration`

React hook that fetches enumeration values reactively. Re-fetches whenever `name` or `parentName` changes.

```typescript theme={"system"}
const values = useEnumeration(name: string, parentName?: string, cached?: boolean): NomenclatorValue[]
```

| Parameter    | Description                           | Type      | Mandatory |
| ------------ | ------------------------------------- | --------- | --------- |
| `name`       | Enumeration name                      | `string`  | ✅         |
| `parentName` | Parent enumeration name for cascading | `string`  | ❌         |
| `cached`     | Use cached result when available      | `boolean` | ❌         |

#### `getEnumeration`

Async function to fetch enumeration values imperatively.

```typescript theme={"system"}
const values = await getEnumeration(name: string, parentName?: string, cached?: boolean)
```

#### `getStaticAsset`

Resolves a static asset URL by its key.

```typescript theme={"system"}
const url = getStaticAsset(key: string)
```

#### `getSubstitutionTag`

Resolves a substitution tag value by its key.

```typescript theme={"system"}
const value = getSubstitutionTag(key: string)
```

***

## Custom CSS

The renderer SDK allows you to pass custom CSS classes on any component inside the process. These classes are then applied to the component's root element.

To add a CSS custom class to a component, you need to define the class in the process designer by navigating to the styles tab of the component, expanding the Advanced accordion and writing down the CSS class.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/add_css_class.gif)

<Warning>
  The classes will be applied last on the element, so they will override the classes already defined on the element.
</Warning>

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/css_class_inspector.png)

## Storybook

Below you find a Storybook which demonstrates how components behave under different states, props, and conditions, it allows you to preview and interact with individual UI components in isolation, without the need for a full-fledged app:

<Card title="Storybook" href="https://storybooks.flowxai.dev/" icon="book" />


# SDKs overview
Source: https://docs.flowx.ai/5.9/sdks/sdks-overview

FlowX.AI web and native mobile SDKs auto-generate UIs from business process definitions for browser and banking app integration.

SDKs are used in the Angular, React, React Native, iOS, and Android applications to render the process screens and orchestrate the custom components.

<CardGroup>
  <Card title="Angular SDK" icon="angular" href="angular-renderer" />

  <Card title="React SDK" icon="react" href="react-renderer" />

  <Card title="React Native SDK" icon="react" href="react-native-renderer" />

  <Card title="iOS SDK" icon="apple" href="ios-renderer" />

  <Card title="Android SDK" icon="android" href="android-renderer" />
</CardGroup>


# IAM solution
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/access-management-overview

Identity and access management (IAM) framework of processes, policies, and technologies for controlling access to digital identities.

## What is an Identity Provider (IdP)?

The IdP, Identity-as-a-Service (IDaaS), Privileged Identity/Access Management (PIM/PAM), Multi-factor/Two-factor Authentication (MFA/2FA), and numerous other subcategories are included in the IAM category.

IdP is a subset of an IAM solution that is dedicated to handling fundamental user IDs. The IdP serves as the authoritative source for defining and confirming user identities.

The IdP can be considered maybe the most important subcategory of the IAM field because it often lays the foundation of an organization's overall identity management infrastructure. In fact, other IAM categories and solutions, such as [IDaaS](https://jumpcloud.com/blog/identity-as-a-service-idaas), PIM/PAM, MFA/2FA, and others are often layered on top of the core IdP and serve to federate core user identities from the IdP to various endpoints. Therefore, your choice in IdP will have a profound influence on your overall IAM architecture.

<Info>
  We recommend **Keycloak**, a component that allows you to create users and store credentials.

  Every communication that comes from a consumer application, goes through a public entry point (API Gateway). To communicate with this component, the consumer application tries to start a process and the public entry point will check for authentication (Keycloak will send you a token) and the entry point validates it.
</Info>

<Info>
  **Authorization split (5.8.0+):** Keycloak is authoritative for authentication, user attributes (used by [business filters](/5.9/docs/platform-deep-dive/user-roles-management/business-filters)), and federation with external IDPs. End-user roles, end-user groups, and project-scoped role assignment are managed in FlowX. See [Runtime authorization](./runtime-authorization).

  Up to 5.7.0, end-user groups were also managed in Keycloak.
</Info>

<Check>
  For more information on how to add roles and how to configure an IdP solution, check the following section:

  <Card title="Configuring an IAM solution" href="configuring-an-iam-solution" icon="file" />
</Check>

## Roles and Keycloak entities reference

Use this section as a quick reference for the named roles, service accounts, and Keycloak realms you will encounter across the FlowX setup guides. Each entry links out to the full configuration page.

### End-user roles

| Name                        | Where it lives                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`FLOWX_ROLE`**            | Keycloak realm role                | Grants permission to start process instances and access active process data from the Designer. Required on the user (or on a mapped end-user group) for any process-start request. The default runtime role assigned when a process is created is the project-level **User** role, managed through [runtime authorization](./runtime-authorization). See [Configuring access roles for processes](../flowx-engine-setup-guide/configuring-access-roles-for-processes). |
| **End-user roles** (5.8.0+) | FlowX                              | Project-scoped roles assigned in FlowX, not in Keycloak. Used to gate Designer-time and runtime actions against specific projects. See [Runtime authorization](./runtime-authorization).                                                                                                                                                                                                                                                                               |
| **End-user groups**         | FlowX (5.8.0+); Keycloak (≤ 5.7.0) | Group end users for bulk role assignment. Managed in FlowX from 5.8.0 onward; previously held in Keycloak.                                                                                                                                                                                                                                                                                                                                                             |

### Backend service accounts

These are Keycloak clients used by FlowX backend services to authenticate against the platform. They live in the **service-accounts realm** (`00000002-0002-4002-8002-000000000002`) and are shared across the installation.

| Client                        | Used by                                |
| ----------------------------- | -------------------------------------- |
| **`flowx-admin-sa`**          | Admin / config services                |
| **`flowx-process-engine-sa`** | Process engine, task-management plugin |

For the full list and the role assignments each one needs, see [Adding service accounts](./configuring-an-iam-solution#adding-service-accounts).

### Keycloak realms

| Realm ID                                                        | Purpose                                                                            |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **`master`**                                                    | Keycloak's built-in admin realm.                                                   |
| **`flowx`** (default name; configurable)                        | The realm where end-user identities, groups, and the `FLOWX_ROLE` realm role live. |
| **`service-accounts`** (`00000002-0002-4002-8002-000000000002`) | Backend service-account clients. Shared across the installation.                   |

<Info>
  End-user **roles** and **groups** are no longer modeled as Keycloak roles or groups starting with 5.8.0. If you are searching for a FlowX role name that you don't see above, it is most likely either an end-user role configured in your own FlowX project (see [Runtime authorization](./runtime-authorization)) or a Keycloak group that was created in your local deployment for token-mapping purposes.
</Info>

## Using Keycloak with an external IdP

<Info>
  Recommended keycloak version: **22.x**
</Info>

In all cases, IdP authentication is mandatory but otherwise, all attribute mapping is configurable, including roles and groups or the entire authorization can be performed by keycloak.

<Frame>
  ![Keycloak integration architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_1.png)
</Frame>

### AD or LDAP provider

In Lightweight Directory Access Protocol (LDAP) and Active Directory, Keycloak functionality is called federation or external storage. Keycloak includes an LDAP/AD provider.

<Frame>
  ![Keycloak LDAP federation architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_2.png)
</Frame>

More details:

<Card title="Server admin LDAP" href="https://www.keycloak.org/docs/26.0.0/server_admin/index.html#_ldap" icon="link" />

Configuration example:

<Card title="LDAP Keycloak" href="https://blog.please-open.it/posts/ldap-bind-proxy/" icon="link" />

### SAML, OpenID Connect, OAuth 2.0

Keycloak functionality is called brokering. Synchronization is performed during user login.

More details:

<Card title="Identity broker" href="https://www.keycloak.org/docs/22.0.5/server_admin/index.html#_identity_broker_first_login" icon="link" />

Configuration examples for ADFS:

<CardGroup>
  <Card title="SAML for React SPA" href="https://blog.samlsecurity.com/post/saml-for-react-spa/" icon="link" />

  <Card title="Keycloak ADFS-OIDC" href="https://www.michaelboeynaems.com/keycloak-ADFS-OIDC.html" icon="link" />
</CardGroup>


# Configuring an IAM solution (Keycloak)
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/configuring-an-iam-solution

This guide provides step-by-step instructions for configuring a minimal Keycloak setup to manage users, roles, and apps efficiently.

This guide walks through configuring a minimal Keycloak setup to efficiently manage users, roles, and apps. Keycloak is an open-source Identity and Access Management (IAM) solution that secures apps and services with little to no coding.

## Prerequisites

Before you begin, ensure you have the following:

* Keycloak installed
* Administrative access to the Keycloak server
* Basic understanding of IAM concepts

***

<Info>
  Recommended Keycloak version: **22.x**

  **Note for Keycloak 26+**: If using Keycloak version 26 or above, additional email configuration is required in the realm settings to prevent bad request errors when creating users. See the realm configuration section for details.
</Info>

## Recommended Keycloak setup

To configure a minimal required Keycloak setup, this guide covers the following steps:

<Steps>
  <Step title="Create a new realm" href="#creating-a-new-realm">
    Define available roles and realm-level roles assigned to new users.
  </Step>

  <Step title="Create new users" href="#creating-new-users" />

  <Step title="Add clients" href="#adding-clients">
    Configure the client authentication, valid redirect URIs, and enable the necessary flows.
  </Step>

  <Step title="Add mappers" href="#adding-protocol-mappers" />

  <Step title="Add service accounts" href="#adding-service-accounts">
    Set up **admin**, **task management**, **process engine**, **scheduler**, **integration designer**, **runtime manager**, **organization manager**, **email gateway**, and **license** service accounts.
  </Step>
</Steps>

Before starting, if you need further information or a broader understanding of Keycloak, refer to the official Keycloak documentation:

<Card title="Keycloak documentation" href="https://www.keycloak.org/documentation" icon="link" />

***

## Creating a new realm

<Info>
  The guided setup flow via the Organization Manager creates both the user realm and the service accounts realm automatically. You only need to follow this section if you are configuring Keycloak manually, or if you need to customize realm settings beyond the defaults.
</Info>

A realm is a space where you manage objects, including users, apps, roles, and groups. Creating a new realm is the first step in setting up Keycloak manually. Follow the steps below to create a new realm in Keycloak:

<Steps>
  <Step title="Log in to the Keycloak Admin Console">
    Log in to the Keycloak Admin Console using the appropriate URL for your environment (e.g., QA, development, production).

    <Frame>
      ![Keycloak Admin Console login page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/iam1.png)
    </Frame>
  </Step>

  <Step title="Create realm">
    In the top left corner dropdown menu, click **Manage realms** then click **Create realm**.

    <Info>
      If you are logged in to the master realm, this dropdown menu lists all the realms created.
    </Info>
  </Step>

  <Step title="Enter realm details">
    Enter a realm name and click **Create**.

    <Frame>
      ![Create realm dialog in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_create_realm.png)
    </Frame>
  </Step>

  <Step title="Configure realm settings">
    **Tokens** → **Access Token Lifespan**: Set to **30 Minutes** (recommended).

    <Frame>
      ![Access token lifespan setting in realm configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_access_token_lifespan.png)
    </Frame>

    **Login** → **Email settings**: Configure email authentication settings.

    <Frame>
      ![Email settings in Keycloak Login tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_email_settings.png)
    </Frame>

    <Warning>
      **For Keycloak versions 26 and above**: You must configure the email settings in the **Login** tab to avoid bad request errors when creating users in FlowX Designer. Make sure to enable **Email as username** and **Login with email** toggles as shown in the realm settings.
    </Warning>
  </Step>
</Steps>

<Check>
  Verify your realm is created correctly: navigate to the realm selector dropdown in Keycloak and confirm your new realm appears in the list.
</Check>

***

## Creating new users

Creating new users is a fundamental part of managing access within Keycloak. Follow these steps to create a new user in a realm and generate a temporary password:

<Steps>
  <Step title="Navigate to users">
    In the left menu bar, click **Users** to open the user list page.
  </Step>

  <Step title="Add a new user">
    Click **Create new user**.

    Fill in the user details and set **Email Verified** to **Yes**.

    <Frame>
      ![Create new user form in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_create_user.png)
    </Frame>
  </Step>

  <Step title="Set temporary password">
    Save the user, go to the **Credentials** tab, and set a temporary password. Ensure the **Temporary** checkbox is checked.

    <Frame>
      ![Setting temporary password in Keycloak Credentials tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_temporary_password.png)
    </Frame>
  </Step>
</Steps>

<Check>
  Verify the user is created: navigate to **Users** and confirm the new user appears in the list with **Email Verified** set to **Yes**.
</Check>

### Password policy

FlowX.AI enforces the following password policy for all user accounts:

| Rule              | Requirement                           |
| ----------------- | ------------------------------------- |
| Minimum length    | 8 characters                          |
| Maximum length    | 64 characters                         |
| Uppercase         | At least one uppercase letter         |
| Lowercase         | At least one lowercase letter         |
| Number            | At least one digit                    |
| Special character | At least one of `!@#$%^&*()_+-`       |
| Additional        | Cannot match the user’s email address |

<Tip>
  Configure your Keycloak realm password policy to match these requirements. In Keycloak, go to **Authentication** → **Policies** → **Password Policy** and add the corresponding policy rules.
</Tip>

***

## Adding clients

A client represents an application instance that is associated with a specific realm.

### Adding an OAuth 2.0 client

Add a client named `flowx-platform-authenticate`, used for login, logout, and refresh token operations by web and mobile apps.

<Steps>
  <Step title="Navigate to Clients">
    Click **Clients** in the top left menu, then click **Create client**.

    <Frame>
      ![Keycloak Clients page with Create client button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_create_client.png)
    </Frame>
  </Step>

  <Step title="Configure general settings">
    In the **General Settings** tab configure the following properties:

    * Set a client ID to `{your-client-name}-authenticate`.
    * Set the **Client type** to `OpenID Connect`.

    <Frame>
      ![Client general settings with Client ID and Client type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_client.png)
    </Frame>
  </Step>

  <Step title="Configure capability config">
    Now click **Next** and configure the **Capability config** details:

    * Enable **Direct Access Grants**.
    * Enable **Implicit Flow Enabled**.

    <Frame>
      ![Capability config with Direct Access Grants and Implicit Flow enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_auth_client_config.png)
    </Frame>
  </Step>

  <Step title="Set valid redirect URIs">
    Click **Next** and configure **Login settings**:

    * Set **Valid redirect URIs**, specifying a valid URI pattern that a browser can redirect to after a successful login or logout, simple wildcards are allowed.

    <Frame>
      ![Login settings with Valid redirect URIs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_auth_client_login_settings.png)
    </Frame>

    <Info>
      **Self-hosted:** The Organization Manager can populate Keycloak redirect URIs for you. If you leave `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` empty, the allowed list is derived from `FLOWX_DEFAULT_DESIGNER_HOMEURI` and `FLOWX_DEFAULT_RUNTIME_HOMEURI` with a `/*` suffix. See [Organization Manager setup — Self-hosted URL configuration](/5.9/setup-guides/organization-manager-setup#self-hosted-url-configuration).
    </Info>
  </Step>

  <Step title="Configure additional settings">
    After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

    * **Front Channel Logout**: Toggle OFF.

    * **Backchannel Logout Session Required**: Toggle OFF.

    <Frame>
      ![Logout settings with Front Channel Logout and Backchannel toggled OFF](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_auth_client_logout_settings.png)
    </Frame>
  </Step>

  <Step title="Add mappers">
    Add **mappers** to `{your-client-name}-authenticate` client.

    <Check>
      For instructions on adding mappers and understanding which mappers to add to your clients, refer to the section on [**Adding Protocol Mappers**](#adding-protocol-mappers).
    </Check>
  </Step>
</Steps>

#### Example configuration for microservices

FlowX services validate incoming tokens using **JWT public key** validation. The shared security library (`application-security-client.yaml`) handles most configuration automatically.

```yaml theme={"system"}
security:
  type: jwt-public-key                                # JWT public key validation
  oauth2:
    base-server-url: https://keycloak.example.com      # Base URL of the Keycloak server
    sa-realm: 00000002-0002-4002-8002-000000000002      # Service accounts realm name (fixed UUID convention) — must match the Realm name field in Keycloak

# Organization manager is a required dependency for all services
flowx:
  lib:
    security:
      services:
        organization-manager:
          base-url: http://organization-manager:80
```

| Configuration Key                                           | Value/Example                          | Description                                                                                                             |
| ----------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `security.type`                                             | `jwt-public-key`                       | Validates tokens using JWT public key (no introspection endpoint needed).                                               |
| `security.oauth2.base-server-url`                           | `https://keycloak.example.com`         | Base URL of the Keycloak server.                                                                                        |
| `security.oauth2.sa-realm`                                  | `00000002-0002-4002-8002-000000000002` | Fixed-UUID name of the service accounts realm — must match the **Realm name** field in Keycloak (not the Display name). |
| `flowx.lib.security.services.organization-manager.base-url` | `http://organization-manager:80`       | Organization manager URL (required dependency for all services).                                                        |

***

## Adding protocol mappers

Protocol mappers in Keycloak allow you to transform tokens and documents, enabling actions such as mapping user data into protocol claims and modifying requests between clients and the authentication server. This provides greater customization and control over the information contained in tokens and exchanged during authentication processes.

<Frame>
  ![Protocol mappers overview in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_11.png)
</Frame>

To enhance your clients' functionality, add the following common mappers:

* [Group Membership mapper ](#group-membership-mapper) (`realm-groups`)
  * Maps user groups to the authorization token.
* [User Attribute mapper](#user-attribute-mapper) (`business filter mapper`)
  * Maps custom attributes, for example, mapping the [businessFilters ](../../docs/platform-deep-dive/user-roles-management/business-filters) list, to the token claim.
* [User Realm role](#user-realm-role-mapper) (`realm-roles`)
  * Maps a user's realm role to a token claim.

<Info>
  The mappers should be configured to be included in the **token introspection** response. Previously, mappers were primarily added to the `/userinfo` endpoint, but modern Keycloak versions support adding them to token introspection, which is the recommended approach for better security and performance.
</Info>

By incorporating these mappers, you can further customize and enrich the information contained within your tokens, ensuring they carry the necessary data for your applications.

### Group membership mapper

Steps to add a Group Membership mapper:

<Steps>
  <Step title="Navigate to Clients">
    From the Keycloak admin console, go to **Clients** and select your desired client.

    <Frame>
      ![Clients list in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_gm.png)
    </Frame>
  </Step>

  <Step title="Select Client Scopes">
    In the client settings, click on **Client Scopes**.

    Select the **dedicated client scope**: `{your-client-name}-authenticate-dedicated` to open its settings.

    <Frame>
      ![Dedicated client scope selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_gm1.png)
    </Frame>
  </Step>

  <Step title="Select client scope">
    Make sure the **Mappers** tab is selected within the dedicated client scope.

    <Frame>
      ![Mappers tab in client scope](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_gm2.png)
    </Frame>
  </Step>

  <Step title="Add a New Mapper">
    Click **Add Mapper**. From the list of available mappers, choose **Group Membership**.

    <Frame>
      ![Add Group Membership mapper from predefined list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_gm3.png)
    </Frame>
  </Step>

  <Step title="Provide mapper details">
    **Name**: Enter a descriptive name for the mapper to easily identify its purpose, for example `realm-groups`.

    **Token Claim Name**: Set the token claim name, typically as `groups`, for including group information in the token.

    **Add to ID Token**: Toggle OFF.

    **Add to token introspection**: Toggle ON.

    <Frame>
      ![Group Membership mapper configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/gm5.png)
    </Frame>
  </Step>
</Steps>

This group membership mapper includes the user's group information in the token for authorization purposes.

### User attribute mapper

To include custom attributes such as business filters in the token claim, follow these steps to add a user attribute mapper:

<Steps>
  <Step title="Navigate to Client Scopes">
    From the Keycloak admin console, go to **Clients** and select your desired client.

    Click on **Client Scopes** and choose `{your-client-name}-authenticate-dedicated` to open its settings.

    Ensure the **Mappers** tab is selected.

    <Frame>
      ![Client scopes Mappers tab for attribute mapper](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/attrMapper1.png)
    </Frame>
  </Step>

  <Step title="Add a New Mapper">
    Click **Add mapper**. From the list of available mappers, select **User Attribute**.
  </Step>

  <Step title="Provide mapper details">
    * **Mapper Type**: Select **User Attribute**.
    * **Name**: Enter a descriptive name for the mapper, such as "Business Filters Mapper".
    * **User Attribute**: Enter `businessFilter`.
    * **Token Claim Name**: Enter `attributes.businessFilters`.
    * **Add to access token**: Toggle ON.
    * **Add to token introspection**: Toggle ON (recommended).
    * **Multivalued**: Toggle ON.
    * **Aggregate attribute values**: Toggle ON.

    <Frame>
      ![User Attribute mapper configuration for business filters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/attrMapper.png)
    </Frame>
  </Step>
</Steps>

This user attribute mapper includes the custom attribute "businessFilters" in the token claim under the name "attributes.businessFilters", making business filter information available within your app.

For more information about business filters, refer to the following section:

<Card title="Business filters" href="../../docs/platform-deep-dive/user-roles-management/business-filters" icon="file" />

### Runtime groups attribute mapper

The `flowxIdPGroups` user attribute carries the FlowX end-user group memberships for a user. The `flowx-platform-authenticate` client emits the value on the access token under `attributes.runtimeGroups` so the runtime authorization service can evaluate per-solution access in a single read.

<Warning>
  **This mapper is not provisioned automatically.** The realm template that ships with `flowx-platform-authenticate` does not include the `flowxIdPGroups → attributes.runtimeGroups` mapper. Any organization that uses external IDP federation needs this mapper added manually before federated logins can resolve runtime permissions. Organizations that manage end users directly in FlowX Keycloak still need it whenever they assign users to end-user groups.
</Warning>

<Steps>
  <Step title="Navigate to Client Scopes">
    From the Keycloak admin console, go to **Clients** and select `flowx-platform-authenticate`. Click **Client Scopes** and choose `flowx-platform-authenticate-dedicated`. Open the **Mappers** tab.
  </Step>

  <Step title="Add a New Mapper">
    Click **Add mapper**. From the list of available mappers, select **User Attribute**.
  </Step>

  <Step title="Provide mapper details">
    * **Mapper Type**: Select **User Attribute**.
    * **Name**: Enter a descriptive name, such as "Runtime Groups Mapper".
    * **User Attribute**: Enter `flowxIdPGroups`.
    * **Token Claim Name**: Enter `attributes.runtimeGroups`.
    * **Add to access token**: Toggle ON.
    * **Add to token introspection**: Toggle ON (recommended).
    * **Multivalued**: Toggle ON.
    * **Aggregate attribute values**: Toggle ON.
  </Step>
</Steps>

The values that appear in `attributes.runtimeGroups` must match the names of [end-user groups](./runtime-authorization#end-user-groups) defined in FlowX. Federated logins populate `flowxIdPGroups` automatically through the [external IDP federation mapper](#external-idp-federation-mapper) below.

<Warning>
  **User attribute schema must accept `flowxIdPGroups`.** This attribute is FlowX-internal and is not part of the realm's declared user profile. The realm's **unmanaged attributes** policy under **Realm settings → User profile** must be set to **Enabled** (the Keycloak default), otherwise the IDP mapper silently drops the value and `attributes.runtimeGroups` arrives empty. The same applies to `businessFilter` and `designerUser`. If your security posture requires unmanaged attributes to be disabled, declare `flowxIdPGroups`, `businessFilter`, and `designerUser` explicitly in the user profile with admin-only edit permissions.
</Warning>

<Tip>
  **Data hygiene at the source.** Group identifiers are matched against FlowX end-user group names by exact string comparison, so trailing whitespace, mixed casing, or stray punctuation in the source IDP's user record will silently break authorization. The `designerUser` attribute is stored on the user record as the string `"true"` or `"false"`; the client mapper handles the conversion to a JSON boolean at token emission via the **Claim JSON Type** setting.
</Tip>

### Designer user attribute

The `designerUser` user attribute is a boolean that flags whether a user has Designer access to the project. The `flowx-platform-authenticate` client exposes it on the access token as `attributes.designerUser`; the runtime authorization service reads the claim to skip role checks for designers running their own projects.

In FlowX-managed Keycloak deployments the attribute is set automatically at organization provisioning, and the mapper ships with the standard client setup. Add the mapper manually only when you operate Keycloak yourself.

<Steps>
  <Step title="Navigate to Client Scopes">
    From the Keycloak admin console, go to **Clients** and select `flowx-platform-authenticate`. Click **Client Scopes** and choose `flowx-platform-authenticate-dedicated`. Open the **Mappers** tab.
  </Step>

  <Step title="Add a New Mapper">
    Click **Add mapper**. From the list of available mappers, select **User Attribute**.
  </Step>

  <Step title="Provide mapper details">
    * **Mapper Type**: Select **User Attribute**.
    * **Name**: Enter a descriptive name, such as "Designer User Mapper".
    * **User Attribute**: Enter `designerUser`.
    * **Token Claim Name**: Enter `attributes.designerUser`.
    * **Add to access token**: Toggle ON.
    * **Add to token introspection**: Toggle ON (recommended).
    * **Multivalued**: Toggle OFF.
    * **Claim JSON Type**: Select **boolean**.
  </Step>
</Steps>

### External IDP federation mapper

This mapper reads the source IDP's group claim and writes the value into the FlowX-side `flowxIdPGroups` user attribute. The [Runtime groups attribute mapper](#runtime-groups-attribute-mapper) above then promotes that user attribute onto the FlowX access token as `attributes.runtimeGroups`.

<Steps>
  <Step title="Open the federated IDP entry">
    From the Keycloak admin console, go to **Identity providers** and open the entry for the federated IDP. Click the **Mappers** tab.
  </Step>

  <Step title="Add a New Mapper">
    Click **Add mapper**. From the **Mapper Type** list, select **Attribute Importer** (Keycloak's `oidc-user-attribute-idp-mapper`; some versions label it **OpenID Connect Attribute to User Attribute**).
  </Step>

  <Step title="Provide mapper details">
    * **Name**: Enter a descriptive name, such as "Source groups to flowxIdPGroups".
    * **Sync Mode Override**: Select **Force** so subsequent logins re-import the value and pick up source-side group changes.
    * **Claim**: Enter the name of the source IDP claim that carries the user's group memberships. The exact name depends on the source IDP — for example, FlowX-to-FlowX federation typically uses `groupsList`; Entra ID typically uses the `groups` claim or a custom extension; AD FS uses whatever the source-side claim emitter is configured to send.
    * **User Attribute**: Enter `flowxIdPGroups`.
  </Step>
</Steps>

<Info>
  **Same recipe for business filters.** If the organization uses business filters, configure a second Attribute Importer mapper that reads the source IDP's business-filter claim and writes it into the `businessFilter` user attribute. The [User attribute mapper](#user-attribute-mapper) section above then exposes it on the token as `attributes.businessFilters`.
</Info>

<Warning>
  **Source-side claim shaping.** Most external IDPs do not emit a single multivalued claim that maps 1:1 to FlowX end-user group names. You typically need a chained mapper on the source IDP side, or on the federated IDP entry, to construct the multivalued array before this mapper imports it. See [Source IDP claim emission](#source-idp-claim-emission) below for the customer-side recipe.
</Warning>

### Source IDP claim emission

The Attribute Importer mapper above reads a single claim from the source IDP's token and writes it into `flowxIdPGroups`. The customer's IDP is responsible for producing that claim. The contract is:

* **Claim name:** customer-choice. The Attribute Importer's **Claim** field absorbs the difference — pick whatever the source IDP already emits (`groups`, `memberOf`, `roles`, a vendor-specific path).
* **Claim type:** multivalued string. Each value is a group identifier that must match an [end-user group](./runtime-authorization#end-user-groups) name in FlowX.
* **Token destinations:** the source IDP must add the claim to the **access token** (Keycloak's broker reads it from there). Adding it to the ID token and userinfo as well is harmless and recommended.

If the customer maintains group data across multiple user attributes — for example, some users have a `groups` array and others have a single-value `role` attribute — they can configure two protocol mappers on the source IDP, both targeting the **same** outgoing claim name with **Aggregate attribute values** toggled ON. Keycloak unions the values into one array before emitting the claim. The same trick works for business filters.

<Tip>
  **Verify the claim before configuring the importer.** Decode a sample access token issued by the source IDP (the **Evaluate** tab on the source-side client is the quickest way) and confirm the group claim is present with the expected name and values. Trailing whitespace, accidental nesting, or single-value strings (instead of arrays) are the most common reasons the FlowX-side Attribute Importer appears to do nothing.
</Tip>

### User realm role mapper

To add a roles mapper to the `{your-client-name}-authenticate` client, so roles will be available in the OAuth user info response, follow these steps:

<Steps>
  <Step title="Navigate to Client Scopes">
    From the Keycloak admin console, go to **Clients** and select your desired client.

    Click on **Client Scopes** and choose `{your-client-name}-authenticate-dedicated` to open its settings.

    Ensure the **Mappers** tab is selected.
  </Step>

  <Step title="Add a New Mapper">
    Click **Add Mapper**. From the list of available mappers, select **User Realm Role**.

    <Frame>
      ![User Realm Role mapper in predefined list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_ua3.png)
    </Frame>
  </Step>

  <Step title="Provide mapper details">
    * **Name**: Enter a descriptive name for the mapper, such as "Roles Mapper".
    * **Mapper Type**: Select **User Realm Role**.
    * **Token Claim Name**: Enter `roles`.
    * **Add to ID Token**: Toggle OFF.
    * **Add to access token**: Toggle OFF.
    * **Add to token introspection**: Toggle ON.

    <Frame>
      ![User Realm Role mapper configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keucloak_ua4.png)
    </Frame>
  </Step>
</Steps>

This roles mapper includes the user's assigned realm roles in the OAuth user info response under the claim name "roles".

<Info>
  You can repeat these steps to add multiple roles mappers if you need to include multiple realm roles in the token claim.
</Info>

<Info>
  **Legacy realm roles.** Realms created from older FlowX realm exports may contain role families such as `ROLE_ADMIN_MANAGE_*`, `ROLE_TASK_MANAGER_*`, or `ROLE_CMS_*`, sometimes already assigned to users. FlowX services assign no built-in meaning to these roles — Designer and platform access is governed by workspace and organization roles plus permissions (see the [roles & permissions matrix](./roles-permissions-matrix)). Realm roles are only evaluated where your own configuration references them, such as swimlane access rules or business filters. Realms provisioned by current FlowX versions no longer include these legacy roles.
</Info>

### Creating a basic client scope

To ensure consistent token configuration across all clients, you should create a default client scope named "basic" with predefined mappers.

<Steps>
  <Step title="Navigate to Client Scopes">
    From the Keycloak admin console, go to **Client Scopes** in the left menu.

    Click **Create client scope**.
  </Step>

  <Step title="Configure client scope settings">
    * **Name**: Enter `basic`.
    * **Type**: Select **Default**.
    * **Protocol**: Select **OpenID Connect**.
    * **Display on consent screen**: Toggle OFF.
    * **Include in token scope**: Toggle ON.

    Click **Save**.
  </Step>

  <Step title="Add predefined mappers">
    In the newly created **basic** client scope, navigate to the **Mappers** tab.

    Add the following predefined mappers:

    1. **sub** mapper:
       * Click **Add mapper** → **From predefined mappers**
       * Select **sub**
       * Click **Add**

    2. **auth\_time** mapper:
       * Click **Add mapper** → **From predefined mappers**
       * Select **auth\_time**
       * Click **Add**
  </Step>

  <Step title="Assign to All Clients">
    After creating the basic client scope, assign it to all your clients:

    1. Navigate to **Clients** in the left menu
    2. For each client (e.g., `flowx-platform-authenticate` and all service accounts):
       * Open the client settings
       * Go to the **Client Scopes** tab
       * Click **Add client scope**
       * Select **basic** from the list
       * Choose **Default** as the assignment type
       * Click **Add**
  </Step>
</Steps>

<Info>
  The **basic** client scope ensures that all clients have consistent token claims for subject identification (sub) and authentication time (auth\_time), which are essential for proper token validation and session management.
</Info>

***

### Examples

#### Login

To request a login token:

```bash theme={"system"}
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin@flowx.ai' \
--data-urlencode 'password=password' \
--data-urlencode 'client_id={your-client-name}-authenticate'
```

#### Refresh token

To refresh an existing token:

```bash theme={"system"}
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id={your-client-name}-authenticate' \
--data-urlencode 'refresh_token=ACCESS_TOKEN'
```

#### User info

To retrieve user information:

```bash theme={"system"}
curl --location --request GET 'localhost:8080/realms/flowx/protocol/openid-connect/userinfo' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
```

***

## Adding service accounts

<Info>
  **What is a service account?**

  A service account grants direct access to the Keycloak API for a specific component. Each client can have a built-in service account that allows it to obtain an access token.

  To use this feature you must turn on **Client authentication** (access type) for your client. When you do this, the **Service Accounts Enabled** switch will appear.
</Info>

### Realm architecture

FlowX uses three Keycloak realms that separate Keycloak administration, user authentication, and service-to-service communication:

| Realm                      | Name                                                             | Purpose                                                                                                                                                                                                              | Which services touch it                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Master realm**           | `master` (Keycloak built-in)                                     | Keycloak's built-in administration realm. FlowX uses admin credentials here briefly during initial provisioning to create the realms below; the master realm itself is not used as a FlowX-managed realm at runtime. | `authorization-system` (and `data-sync` during the runtime-authorization migration) — **only when `SECURITY_KEYCLOAKADMINENABLED=true`**. No other service ever touches it.                                          |
| **User realm**             | A fixed-UUID name (e.g., `00000001-0001-4001-8001-000000000001`) | Main FlowX realm where end users live: users, roles, groups, and the `flowx-platform-authenticate` client.                                                                                                           | Frontend apps and end-user authentication flows. Backend services also reach this realm to fetch the public JWKS keys used to validate inbound tokens issued by it. Almost every service is configured with its URL. |
| **Service accounts realm** | `00000002-0002-4002-8002-000000000002` (fixed)                   | Holds the backend service-account clients (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Managed and isolated from the user realm.                                                                             | **Every backend service** — they obtain access tokens here via `security.oauth2.sa-realm`.                                                                                                                           |

This separation improves security isolation — service accounts cannot access user tokens, user realm changes do not affect service-to-service authentication, and the master realm stays restricted to administrative use.

**Where to create each client:**

* **User-facing clients** (`flowx-platform-authenticate`) go in the **user realm**
* **All service account clients** (`flowx-*-sa`) go in the **service accounts realm**
* **No FlowX clients** are created in the master realm — it only holds Keycloak's built-in `admin-cli`

<Info>
  Both realms are created automatically by the guided setup flow on fresh installations, and by Liquibase migrations on upgrades — the existing user realm is renamed and the service accounts are moved out into the new SA realm.

  If your deployment does not grant Keycloak admin credentials to FlowX services, you must create the service accounts realm and move the service account clients manually. See [Manual Keycloak configuration](#manual-keycloak-configuration) below.
</Info>

**Authorization system master realm configuration**

By default, the authorization-system service accesses the Keycloak master realm to manage realms and run migrations. This is controlled by `SECURITY_KEYCLOAKADMINENABLED` (default `true`). Configure the following properties on the authorization-system service only:

| Environment Variable                  | Description                                                                                                                                                                          | Default Value |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `SECURITY_KEYCLOAKADMINENABLED`       | Whether FlowX has Keycloak admin access and manages realms. Set to `false` to skip FlowX-managed realm administration; the `SECURITY_MASTERREALM_*` variables are then not required. | `true`        |
| `SECURITY_MASTERREALM_ADMIN_CLIENTID` | Master realm admin client ID                                                                                                                                                         | `admin-cli`   |
| `SECURITY_MASTERREALM_NAME`           | Master realm name                                                                                                                                                                    | `master`      |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username                                                                                                                                                              | -             |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password                                                                                                                                                              | -             |

The admin user supplied here must hold the **Admin** role on the master realm with permission to create realms — at first boot, the authorization-system service creates the user realm and the service-accounts realm, along with the clients, users, and service accounts within them.

<Warning>
  These credentials grant full Keycloak administrative access. Store them securely using your secrets management solution (e.g., Vault, Kubernetes secrets). Never commit them to version control.
</Warning>

***

### Admin service account

The admin service account is used by the admin microservice to connect with Keycloak, enabling user and group management features within the FlowX.AI Designer.

Steps to add an Admin service account:

<Steps>
  <Step title="Create the Client">
    Navigate to **Clients** and select **Create client**.

    Enter a **Client ID** for your new client.

    <Frame>
      ![Admin service account client ID setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/admin-sa1.png)
    </Frame>
  </Step>

  <Step title="Configure capability config">
    * Enable **Client authentication** (access type).
    * Disable **Standard flow**.
    * Disable **Direct access grants**.
    * Enable **Service accounts roles**.

    <Frame>
      ![Service account capability config with Client authentication and Service accounts roles enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/admin-sa2.png)
    </Frame>
  </Step>

  <Step title="Configure additional settings">
    After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

    * **Backchannel Logout Session Required**: Toggle OFF.

    * **Front Channel Logout**: Toggle OFF.

    <Frame>
      ![Logout settings toggled OFF for service account](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/admin-sa3.png)
    </Frame>
  </Step>

  <Step title="Configure service account roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    <Frame>
      ![Service accounts roles tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/admin-sa5.png)
    </Frame>

    <Warning>
      **Important**: The admin service account no longer requires client roles from realm-management. If you have existing roles assigned, remove them to follow the updated security model.
    </Warning>

    The admin service account is now configured to work without specific client roles. Authentication and authorization will be managed through the service account token itself.
  </Step>
</Steps>

<Info>
  The admin service account does not require mappers or specific client roles. Authentication is handled through the service account token itself.
</Info>

### Task Management service account

The task management service account facilitates process initiation and enables the use of the task management plugin (requiring the `FLOWX_ROLE` and role mapper).

<Info>
  Starting with 5.9.0, the Task Management plugin no longer reads user data from Keycloak; task operations resolve users through FlowX runtime authorization. The service account no longer needs any realm-management client roles.
</Info>

Steps to Add a Task Management service account:

<Steps>
  <Step title="Create the Service Account">
    Follow steps **1**-**3** as in the Admin Service account configuration: [Admin service account](#admin-service-account).
  </Step>

  <Step title="Add a realm roles mapper">
    In the newly created task management plugin service account, select **Client Scopes**:

    Click on `{your-client-name}-service-account` to open its settings.

    <Info>
      Ensure the Mappers tab is selected within the dedicated client scope.
    </Info>

    Click **Add mapper**. From the list of available mappers, select **User Realm Role**.

    <Frame>
      ![Adding User Realm Role mapper to task management SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tsk-mapper.png)
    </Frame>
  </Step>

  <Step title="Configure the mapper">
    **Name**: Enter a descriptive name for the mapper to easily identify its purpose, for example `realm-roles`.

    **Token Claim Name**: Set it to `roles`.

    Disable **Add to ID token**.

    <Frame>
      ![Realm roles mapper configuration for task management SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/gm7.png)
    </Frame>

    Click **Save**.

    <Frame>
      ![Saved realm roles mapper](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/md2.png)
    </Frame>
  </Step>

  <Step title="Add the service account realm role">
    Assign the `FLOWX_ROLE` service account realm role (used to grant permissions for starting processes).

    <Info>
      The `FLOWX_ROLE` realm role is used to grant permissions for starting processes in the FlowX.AI Designer platform.
    </Info>
  </Step>
</Steps>

### Process engine service account

The process engine requires a service account for service-to-service authentication and authorization.

<Info>
  This service account is also needed to be able to use [**Start Catch Event**](../../docs/building-blocks/node/message-events/message-catch-start-event) node.
</Info>

<Steps>
  <Step title="Create the Client">
    Follow steps **1-3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).
  </Step>

  <Step title="Configure service account roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    The process engine service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.
  </Step>

  <Step title="Add a realm roles mapper">
    In the newly created process engine service account, select **Client Scopes**.

    Click on `{your-client-name}-service-account` to open its settings.

    Ensure the **Mappers** tab is selected within the dedicated client scope.

    Click **Add mapper**. From the list of available mappers, select **User Realm Role**.

    Configure the mapper:

    * **Name**: Enter `realm-roles`
    * **Token Claim Name**: Set it to `roles`
    * **Add to ID token**: Toggle OFF
    * **Add to token introspection**: Toggle ON

    <Frame>
      ![Adding realm roles mapper to process engine SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/realm_roles_engine.gif)
    </Frame>
  </Step>
</Steps>

### Scheduler service account

<Info>
  This service account is used for [**Start Timer Event**](../../docs/building-blocks/node/timer-events/timer-start-event) node. The registered timers in the scheduler require sending a process start message to Kafka. Authentication is also necessary for this operation.
</Info>

The configuration is similar to the **process engine service account**:

<Steps>
  <Step title="Create the Client">
    Follow steps **1-3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).
  </Step>

  <Step title="Configure service account roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    The scheduler service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.
  </Step>

  <Step title="Add a realm roles mapper">
    Add a **realm-roles** mapper (as shown in the example for process-engine service account):

    In the scheduler service account, select **Client Scopes**.

    Click on `{your-client-name}-service-account` to open its settings.

    Ensure the **Mappers** tab is selected within the dedicated client scope.

    Click **Add mapper**. From the list of available mappers, select **User Realm Role**.

    Configure the mapper:

    * **Name**: Enter `realm-roles`
    * **Token Claim Name**: Set it to `roles`
    * **Add to ID token**: Toggle OFF
    * **Add to token introspection**: Toggle ON

    <Frame>
      ![Realm roles mapper for scheduler SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/md5.png)
    </Frame>
  </Step>
</Steps>

### Integration Designer service account

The Integration Designer service account is used by the integration designer microservice to interact securely with Keycloak, enabling it to manage various integrations within the FlowX.AI platform.

Steps to set up an Integration Designer service account:

<Steps>
  <Step title="Create the Client">
    * In Keycloak, navigate to **Clients** and select **Create client**.
    * Enter a **Client ID** for your new client (e.g., `flowx-integration-designer-sa`).

    <Frame>
      ![Integration Designer SA client ID setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/keycloak/id-sa.png)
    </Frame>
  </Step>

  <Step title="Configure client capabilities">
    * Enable **Client authentication** under access type.
    * Enable **Service accounts roles** to allow the account to manage integrations.

    <Frame>
      ![Integration Designer SA capability config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/keycloak/Screenshot%202024-11-05%20at%2013.58.06.png)
    </Frame>
  </Step>

  <Step title="Save the Client Configuration">
    * Skip the **Login settings** page.
    * Click **Save** to apply the configuration.
  </Step>

  <Step title="Assign service account client roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    Click **Assign role** and in the Filter field, select **Filter by clients**.

    Assign only the **view-users** role from realm-management:

    <Info>
      Remove any other roles if they are assigned. The integration designer service account should only have the **view-users** client role.
    </Info>
  </Step>
</Steps>

### Authorization System service account

The Authorization System service account is used for managing user authentication and authorization operations, including user management, realm configuration, and access control within the FlowX.AI platform.

Steps to set up an Authorization System service account:

<Steps>
  <Step title="Create the Client">
    Navigate to **Clients** and select **Create client**.

    Enter a **Client ID** for your new client (e.g., `flowx-authorization-system-sa`).
  </Step>

  <Step title="Configure capability config">
    * Enable **Client authentication** (access type).
    * Disable **Standard flow**.
    * Disable **Direct access grants**.
    * Enable **Service accounts roles**.
  </Step>

  <Step title="Configure additional settings">
    After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

    * **Backchannel Logout Session Required**: Toggle OFF.
    * **Front Channel Logout**: Toggle OFF.
  </Step>

  <Step title="Assign service account client roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    Click **Assign role** and in the Filter field, select **Filter by clients**.

    Assign the following service account client roles from realm-management:

    * **view-users**
    * **query-users**
    * **manage-users**
    * **manage-realm**

    <Info>
      These roles are essential for the Authorization System service account to perform user and realm management operations within Keycloak.
    </Info>
  </Step>
</Steps>

### Runtime manager service account

The runtime manager service account is used by both Application Manager and Runtime Manager services to connect with Keycloak and perform export/import operations for builds, application versions, or other resource-specific tasks.

Steps to add a Runtime manager service account:

<Steps>
  <Step title="Create the Client">
    Navigate to **Clients** and select **Create client**.

    Enter a **Client ID** for your new client.

    <Frame>
      ![Runtime manager SA client ID setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-16%20at%2018.19.59.png)
    </Frame>
  </Step>

  <Step title="Configure capability config">
    * Enable **Client authentication** (access type).
    * Disable **Standard flow**.
    * Disable **Direct access grants**.
    * Enable **Service accounts roles**.

    <Frame>
      ![Runtime manager SA capability config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-16%20at%2018.24.21.png)
    </Frame>
  </Step>

  <Step title="Configure additional settings">
    After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

    * **Backchannel Logout Session Required**: Toggle OFF.

    * **Front Channel Logout**: Toggle OFF.

    <Frame>
      ![Logout settings toggled OFF for service account](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/admin-sa3.png)
    </Frame>
  </Step>

  <Step title="Configure service account roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    <Frame>
      ![Service accounts roles tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/admin-sa5.png)
    </Frame>

    <Warning>
      **Important**: The runtime manager service account no longer requires specific realm roles. If you have existing roles assigned (such as ROLE\_TASK\_MANAGER\_HOOKS\_ADMIN, ROLE\_ADMIN\_MANAGE\_PROCESS\_ADMIN, etc.), remove them to follow the updated security model.
    </Warning>

    The runtime manager service account is now configured to work without specific realm roles. Authentication and authorization for export/import operations will be managed through the service account token itself.
  </Step>
</Steps>

### Organization manager service account

The organization manager service account is used by the organization manager microservice to handle organization and workspace management within the FlowX.AI platform.

<Steps>
  <Step title="Create the Client">
    Follow steps **1**-**3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

    Enter a **Client ID** of `flowx-organization-manager-sa`.
  </Step>

  <Step title="Configure service account roles">
    In the newly created client, navigate to the **Service accounts roles** tab.

    The organization manager service account does not require specific client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.
  </Step>
</Steps>

### Email gateway service account

The email gateway service account is used by the email gateway microservice to manage email sending and receiving operations within the FlowX.AI platform.

<Steps>
  <Step title="Create the Client">
    Follow steps **1**-**3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

    Enter a **Client ID** of `flowx-email-gateway-sa`.
  </Step>
</Steps>

<Info>
  The email gateway service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.
</Info>

### License service account

The license service account is used by the license microservice to manage license validation and enforcement within the FlowX.AI platform.

<Steps>
  <Step title="Create the Client">
    Follow steps **1**-**3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

    Enter a **Client ID** of `flowx-license-sa`.
  </Step>
</Steps>

<Info>
  The license service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.
</Info>

***

## Configuring SA\_FLOWX realm role

The `SA_FLOWX` role is a realm-level role that should be assigned to all service accounts to ensure proper authentication and authorization across the FlowX.AI platform.

<Info>
  Create the `SA_FLOWX` role in the **service accounts realm** (`00000002-0002-4002-8002-000000000002`), since that is where all service account clients reside.
</Info>

<Steps>
  <Step title="Create the SA_FLOWX Realm Role">
    1. In the Keycloak admin console, navigate to the service accounts realm (`00000002-0002-4002-8002-000000000002`).
    2. Go to **Realm roles** in the left menu.
    3. Click **Create role**.
    4. Enter `SA_FLOWX` as the **Role name**.
    5. Add a description: "Service account role for FlowX.AI platform services".
    6. Click **Save**.
  </Step>

  <Step title="Assign SA_FLOWX to service accounts">
    For each service account listed below, assign the `SA_FLOWX` realm role:

    * **flowx-process-engine-sa**
    * **flowx-admin-sa**
    * **flowx-runtime-manager-sa**
    * **flowx-integration-designer-sa**
    * **flowx-scheduler-core-sa**
    * **flowx-authorization-system-sa**
    * **flowx-task-management-plugin-sa**
    * **flowx-organization-manager-sa**
    * **flowx-email-gateway-sa**
    * **flowx-license-sa**
    * **flowx-webhook-gateway-sa**
    * **flowx-file-gateway-sa**
    * **flowx-ai-gateway-sa**

    To assign the role to each service account:

    1. Navigate to **Clients** and select the service account client.
    2. Go to the **Service accounts roles** tab.
    3. Click **Assign role**.
    4. In the Filter field, select **Filter by realm roles**.
    5. Find and select **SA\_FLOWX** from the list.
    6. Click **Assign**.

    <Frame>
      ![Assigning SA\_FLOWX realm role to a service account](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/flowx_role.gif)
    </Frame>
  </Step>

  <Step title="Verify role assignment">
    After assigning the role to all service accounts, verify that each service account has the `SA_FLOWX` role listed in its **Service accounts roles** tab.

    <Info>
      The `SA_FLOWX` role ensures consistent authentication and authorization behavior across all FlowX.AI platform services. Make sure all service accounts have this role assigned for proper system operation.
    </Info>
  </Step>
</Steps>

***

## Email (SMTP) configuration

<Info>
  **Required for self-hosted deployments**

  On self-hosted deployments, SMTP must be configured by the client directly in Keycloak. This is required for password reset flows and user invitation emails sent from FlowX Designer.
</Info>

To configure email delivery:

<Steps>
  <Step title="Navigate to email settings">
    In Keycloak, go to your organization realm, then **Realm settings** → **Email**.
  </Step>

  <Step title="Configure SMTP connection details">
    Fill in your SMTP server details:

    | Field                                | Description                                            |
    | ------------------------------------ | ------------------------------------------------------ |
    | **Host**                             | SMTP server hostname (e.g., `smtp.example.com`)        |
    | **Port**                             | SMTP port (typically `587` for TLS or `465` for SSL)   |
    | **From**                             | Sender email address (e.g., `noreply@example.com`)     |
    | **Enable SSL** / **Enable StartTLS** | Toggle **ON** based on your mail server requirements   |
    | **Authentication**                   | Toggle **ON** if your SMTP server requires credentials |
    | **Username** / **Password**          | SMTP authentication credentials                        |
  </Step>

  <Step title="Test the connection">
    Use the **Test connection** button in Keycloak to verify emails can be sent.
  </Step>
</Steps>

<Warning>
  Without SMTP configured, the following features will not work:

  * **Password reset** — users cannot reset their passwords via email
  * **User invitations** — inviting new users from FlowX Designer will fail
</Warning>

***

## Manual Keycloak configuration

If FlowX services do not have Keycloak admin access, perform the following steps manually in the Keycloak Admin Console:

<Steps>
  <Step title="Create the service accounts realm">
    1. Log in to the Keycloak Admin Console.
    2. Click **Create realm**.
    3. Set the **Realm name** to `00000002-0002-4002-8002-000000000002`.
    4. Set the **Display name** to `Flowx Administration Realm`.
    5. Click **Create**.

    Configure the realm settings:

    * **Login** tab: Enable **Email as username** and **Login with email**
    * **Authentication** → **Policies** → **Password Policy**: Add uppercase, digit, special character, and minimum length (8) rules
  </Step>

  <Step title="Move service account clients to the SA realm">
    For each service account client listed in [Adding service accounts](#adding-service-accounts), create the client in the **service accounts realm** (not the user realm):

    1. In the SA realm, go to **Clients** → **Create client**.
    2. Enter the **Client ID** (e.g., `flowx-admin-sa`).
    3. Enable **Client authentication** and **Service accounts roles**. Disable **Standard flow** and **Direct access grants**.
    4. Configure **Logout Settings**: Toggle **OFF** both Backchannel Logout and Front Channel Logout.
    5. Assign the `SA_FLOWX` realm role (create it first in the SA realm if it does not exist).
  </Step>

  <Step title="Create the anonymous service account">
    The `flowx-anonymous-sa` client is used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows (see the full list of consuming services in the [v5.9 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#anonymous-service-account-shared-client-secret)). It is intentionally scoped to a separate, lower-privilege realm role so a leaked token cannot exercise authenticated paths.

    1. In the SA realm, create a new realm role named **`SA_FLOWX_ANONYMOUS`**. Do **not** reuse `SA_FLOWX`.
    2. Go to **Clients** → **Create client**.
    3. Enter the **Client ID** `flowx-anonymous-sa`.
    4. Enable **Client authentication** and **Service accounts roles**. Disable **Standard flow** and **Direct access grants**.
    5. Configure **Logout Settings**: Toggle **OFF** both Backchannel Logout and Front Channel Logout.
    6. Assign **only** the `SA_FLOWX_ANONYMOUS` realm role to this client's service account. Do not assign `SA_FLOWX`.

    <Warning>
      **Do not assign `SA_FLOWX` to `flowx-anonymous-sa`.** The whole point of this client is to keep the anonymous-flow blast radius narrow — if the token leaks, the attacker can only invoke paths reachable to an anonymous internet visitor on processes or UI flows that explicitly opted into the `Anonymous` runtime role. Granting `SA_FLOWX` removes that boundary.
    </Warning>

    <Info>
      After creating the client, take the generated client secret and configure it on every consuming service via `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET`. The same secret must be set on all of them. See [Anonymous service account: shared client secret](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#anonymous-service-account-shared-client-secret) in the v5.9 deployment guidelines for the full list of services and the matching Liquibase parameter.
    </Info>
  </Step>

  <Step title="Configure the org_id protocol mapper">
    In the **user realm**, ensure the `flowx-platform-authenticate` client has a protocol mapper that adds the `org_id` claim to access tokens:

    1. Go to **Clients** → `flowx-platform-authenticate` → **Client scopes** → dedicated scope.
    2. **Add mapper** → **By configuration** → **Hardcoded claim**.
    3. Set **Name** to `org_id`, **Token Claim Name** to `org_id`, **Claim value** to the user realm name (the UUID used for that realm), and **Claim JSON Type** to `String`.
    4. Enable **Add to access token** and **Add to token introspection**.
  </Step>

  <Step title="Remove service accounts from user realm">
    After creating the service account clients in the SA realm, delete the old service account clients from the user realm. Keep only user-facing clients (`flowx-platform-authenticate`) in the user realm.
  </Step>
</Steps>

<Warning>
  If you skip manual configuration, service-to-service authentication will fail. All FlowX backend services expect service accounts to exist in the realm identified by `security.oauth2.sa-realm` (`00000002-0002-4002-8002-000000000002`).
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bad request error when creating users in FlowX Designer" icon="triangle-exclamation">
    **Keycloak 26+ only**: You must configure email settings in the **Login** tab of realm settings. Toggle **ON** both **Email as username** and **Login with email**. Without this configuration, user creation requests from FlowX Designer fail with a bad request error.
  </Accordion>

  <Accordion title="Realm name conflict" icon="triangle-exclamation">
    Ensure the realm name is unique within your Keycloak instance. Duplicate realm names cause creation failures.
  </Accordion>

  <Accordion title="Service account authentication fails" icon="triangle-exclamation">
    Verify the following:

    * The service account client has **Client authentication** enabled and **Service accounts roles** toggled **ON**.
    * The `SA_FLOWX` realm role is assigned to the service account.
    * The client secret in your deployment matches the secret in Keycloak (**Clients** → select client → **Credentials** tab).
    * `security.oauth2.sa-realm` is set to `00000002-0002-4002-8002-000000000002` and the service account client exists in the SA realm (not the user realm).
  </Accordion>

  <Accordion title="Token missing groups, roles, or business filters" icon="triangle-exclamation">
    Check that the required protocol mappers are configured on the correct client scope:

    * **Group Membership** mapper with **Add to token introspection** toggled **ON**.
    * **User Realm Role** mapper with **Add to token introspection** toggled **ON**.
    * **User Attribute** mapper for business filters with **Multivalued** and **Aggregate attribute values** toggled **ON**.
    * The `org_id` protocol mapper is configured on the `flowx-platform-authenticate` client in the user realm.
  </Accordion>

  <Accordion title="JWT validation fails" icon="triangle-exclamation">
    * Verify `security.type` is set to `jwt-public-key`.
    * Ensure `security.oauth2.sa-realm` is set to `00000002-0002-4002-8002-000000000002`.
    * Verify that `flowx.lib.security.services.organization-manager.base-url` is set and the organization-manager service is reachable.
  </Accordion>
</AccordionGroup>

***

## Summary

By following these steps, you have a minimal Keycloak setup to manage users, roles, and apps efficiently.

Your Keycloak setup should include:

* A **user realm** (named with a fixed UUID) containing the `flowx-platform-authenticate` client, protocol mappers, users, roles, and groups
* A **service accounts realm** (`00000002-0002-4002-8002-000000000002`) containing all `flowx-*-sa` service account clients with the `SA_FLOWX` realm role
* **SMTP configured** in the user realm for password reset and user invitations (required for self-hosted deployments)
* **JWT public key validation** (`security.type: jwt-public-key`) on all services
* **Master realm credentials** configured on the authorization-system service

For more detailed configurations and advanced features, refer to the official Keycloak documentation.

***

## Related resources

<CardGroup>
  <Card title="Access Management overview" icon="shield-halved" href="./access-management-overview">
    User roles, groups, and access control
  </Card>

  <Card title="Business filters" icon="filter" href="../../docs/platform-deep-dive/user-roles-management/business-filters">
    Data-level access control using business filters
  </Card>

  <Card title="Keycloak documentation" icon="link" href="https://www.keycloak.org/documentation">
    Official Keycloak documentation
  </Card>
</CardGroup>


# Configuring an IAM solution (EntraID)
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/configuring-an-iam-solution-entra

This guide provides step-by-step instructions for configuring a minimal EntraId setup to manage users, roles, and applications efficiently.

## Overview

Microsoft Entra is Microsoft’s unified identity and access management solution designed to protect access to applications, resources, and user data across an organization’s environment. It provides an identity and access management (IAM) framework, allowing secure access control, role management, and integration of various applications under a single directory. Entra is crucial for managing multi-cloud and hybrid environments securely, enforcing policies, and supporting both self-hosted and cloud resources.

## Prerequisites

* Application Administrator role
* Basic understanding of IAM and OIDC concepts

## Recommended EntraID setup

This setup configures Microsoft Entra to manage and secure access for FlowX.AI applications, handling user roles, custom attributes, and application-specific permissions. The setup covers these main components:

<AccordionGroup>
  <Accordion title="1. Application Registrations">
    * Flowx-Web and Flowx-API are the core applications that act as entry points for the FlowX.AI platform. Additional applications like Flowx-Admin, Task Management Plugin, and Scheduler Core are registered to support specific functionalities.
    * Each application registration includes settings for authentication, API permissions, and role assignments.
  </Accordion>

  <Accordion title="2. Authentication and Authorization">
    * Configures OAuth 2.0 and OIDC protocols, enabling secure access to resources.
    * Roles and permissions are assigned through Entra, and single sign-on (SSO) is set up for ease of access across applications.
  </Accordion>

  <Accordion title="3. Token and API Permissions">
    * Token Configuration includes defining claims (e.g., `email`, `groups`) for use in JWTs, which are used for secure identity validation across services.
    * API Permissions are managed using Microsoft Graph, which governs access to resources like user profiles and groups within FlowX.AI.
  </Accordion>

  <Accordion title="4. Custom Attributes">
    Custom attribute extensions (e.g., `businessFilter`) allow organizations to apply additional filters or metadata to user and group profiles, configured and managed using Microsoft Graph CLI.
  </Accordion>

  <Accordion title="5. Helm Chart Configuration">
    * Helm charts provide a structured setup for deploying FlowX.AI applications in containerized environments.
    * Key values such as `tenant_id`, `client_id`, and `client_secret` are configured to support authentication and secure access.
  </Accordion>

  <Accordion title="6. Example JWT Tokens">
    JWT tokens are configured to carry user claims, roles, and custom attributes, ensuring that each token provides comprehensive identity details for FlowX.AI applications.
  </Accordion>
</AccordionGroup>

### Flowx-web app registration

The Flowx-web application serves as the main entry point for logging into FloWX Designer or container applications.

#### Appplication registration steps

To register the Flowx-web application, follow these steps:

1. Navigate to [https://portal.azure.com](https://portal.azure.com) and log in to your EntraID directory, which will host your FlowX.AI application registrations.
2. Go to **Microsoft EntraID > App registrations > New registration**

<Frame>
  ![Entra ID App registrations page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%283%29.png)
</Frame>

3. Enter a name for your application, then select **Accounts in this organizational directory only (Single tenant)** to limit access to your organization’s directory.

<Frame>
  ![Flowx-web app registration form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2010.56.35.png)
</Frame>

4. Click **Register** to complete the setup.

<Info>
  You will be redirected to the overview of the newly created app registration.
</Info>

#### Authentication steps

Follow these steps to configure authentication for the Flowx-web application:

1. Go to the **Authentication** tab. Under **Platform configurations**, add a new platform by selecting **Single-page application (SPA)**. Then, set the **Redirect URIs** to point to the URIs of your Designer application.

<Frame>
  ![Adding SPA platform configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/2024-11-04%2010.54.45.gif)
</Frame>

<Frame>
  ![SPA redirect URI configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2010.58.31.png)
</Frame>

2. Click **Configure** to save the platform settings.
3. Next, click **Add URI** to include an additional redirect URI, this time pointing to your container application's URI.

<Frame>
  ![Adding additional redirect URI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2017.14.29.png)
</Frame>

<Frame>
  ![Container app redirect URI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.31.19.png)
</Frame>

4. Click **Save** to confirm the redirect URI changes.
5. Scroll down to **Advanced Settings**. Under **Mobile and Desktop Applications**, toggle **Enable the following mobile and desktop flows** to **Yes**.

<Frame>
  ![Mobile and desktop flow toggle setting](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2017.16.55.png)
</Frame>

6. Click **Save** again to apply all changes.

#### API permissions

To configure the necessary API permissions, follow these steps:

1. Navigate the **API permissions** tab and click **Add a permission**.

<Frame>
  ![API permissions tab with Add a permission button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.33.31.png)
</Frame>

2. In the permissions menu, select **Microsoft Graph** and then choose **Delegated permissions**.

<Frame>
  ![Selecting Microsoft Graph permissions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.35.56.png)
</Frame>

<Frame>
  ![Delegated permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.36.46.png)
</Frame>

3. Add the following permissions by selecting each option under **OpenId permissions**:

* email
* offline\_access
* openid
* profile

<Frame>
  ![OpenID permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.38.35.png)
</Frame>

4. After adding these permissions, click **Add permissions** to confirm.

#### Token configuration

Configure the claims you want to include in the ID token.

1. Navigate to the **Token configuration** tab. Click **Add optional claim**, then select **Token type > Access**.

* Choose the following claims to include in the token:
  * email
  * family\_name
  * given\_name
  * preferred

<Frame>
  ![Adding optional token claims](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.40.21.png)
</Frame>

2. Click **Add** to save these optional claims.

<Frame>
  ![Optional claims confirmation dialog](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.41.33.png)
</Frame>

3. Next, add group claims to the token by clicking **Add groups claim**.
4. Select **All groups** and, under each token type, select **sAMAccountName** (this may differ for your specific organization).

<Frame>
  ![Group claims configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%285%29.png)
</Frame>

#### Setting token expiration policies

For organizations that require specific control over token lifetimes, Microsoft Entra allows customization of token expiration policies.

1. **Create a Custom Token Lifetime Policy**: Define the desired expiration settings for access, ID, and refresh tokens in the policy.
2. **Assign the Policy to a Service Principal**: Apply the policy to your Flowx-web or Flowx-API app registrations to enforce token lifetime requirements.

<Tip>
  For more details on creating and assigning policies for token expiration, refer to [**Microsoft's guide on configuring token lifetimes**](https://learn.microsoft.com/en-us/entra/identity-platform/configure-token-lifetimes#create-a-policy-and-assign-it-to-a-service-principal).
</Tip>

<Info>
  Adjusting token lifetimes can enhance security by reducing the window for unauthorized access.
</Info>

***

### Flowx-API app registration

The Flowx-API application is used to configure the access token necessary for secure communication between the browser and all exposed FlowX APIs.

#### Appplication registration steps

To register the Flowx-API application, follow these steps:

1. Navigate to [https://portal.azure.com](https://portal.azure.com) and log in to your EntraID directory, which will host your FlowX.AI application registrations.
2. Go to **Microsoft EntraID > App registrations > New registration**

<Frame>
  ![Entra ID App registrations page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%283%29.png)
</Frame>

3. Enter a name for your application, then select **Accounts in this organizational directory only (Single tenant)** to limit access to your organization’s directory.

<Frame>
  ![Flowx-API app registration form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2012.04.27.png)
</Frame>

4. Click **Register** to complete the setup.

<Info>
  You will be redirected to the overview page of the newly created app registration.
</Info>

#### API permissions

To configure the necessary API permissions, follow these steps:

1. Go to the **API permissions** tab and click **Add a permission**.

<Frame>
  ![Flowx-API API permissions tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/ent1.png)
</Frame>

2. In the permissions menu, select **Microsoft Graph** and then choose **Delegated permissions**.

<Frame>
  ![Selecting Microsoft Graph permissions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.35.56.png)
</Frame>

<Frame>
  ![Delegated permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.36.46.png)
</Frame>

3. Add the following permissions by selecting each option under **OpenId permissions**:

* email
* offline\_access
* openid
* profile

<Frame>
  ![OpenID permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.38.35.png)
</Frame>

4. After adding these permissions, click **Add permissions** to confirm.

#### Token configuration

Configure the claims you want to include in the ID token.

1. Navigate to the **Token configuration** tab. Click **Add optional claim**, then select **Token type > Access**.

* Choose the following claims to include in the token:
  * email
  * family\_name
  * given\_name
  * preferred

<Frame>
  ![Flowx-API optional token claims selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2015.36.40.png)
</Frame>

2. Click **Add** to save these optional claims.
3. Next, add group claims to the token by clicking **Add groups claim**.
4. Select **All groups** and, under each token type, select **sAMAccountName** (this may differ for your specific organization).

<Frame>
  ![Flowx-API group claims configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2016.14.01.png)
</Frame>

#### Expose an API

To configure the API exposure and define scopes:

1. In the **Expose an API** section, click **Add** under **Application ID URI**. It’s recommended to use the application’s name for consistency.

<Frame>
  ![Expose an API section with Application ID URI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.11.53.png)
</Frame>

2. Click **Save**.
3. Under **Scopes defined by this API**, click **Add a scope** and configure it as follows:

* **Scope name**: `FlowxAI.ReadWrite.All`
* **Who can consent**: Admins and users
* **Admin consent display name**: Full API Access for FlowX.AI Platform
* **Admin consent description**: Grants this application full access to all available APIs, allowing it to read, write, and manage resources across the FlowX.AI platform.
* **User consent display name**: Same as admin consent display name
* **User consent description**: Same as admin consent description
* **State**: Enabled

<Frame>
  ![API scope configuration form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.16.52.png)
</Frame>

<Info>
  This scope is not used directly to grant permissions. Instead, it is included in login requests made from a web client. When a client makes a login request with this scope, Entra ID uses it to identify and provide the appropriate access token configured here, ensuring secure access.
</Info>

4. Under **Authorized client applications**, click **Add a client application**. Add each of the following client applications, selecting the `FlowxAI.ReadWrite.All` scope:

* flowx-web
* flowx-admin
* flowx-process-engine
* flowx-integration-designer
* flowx-task-management-plugin
* flowx-scheduler-core

<Frame>
  ![Authorized client applications list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.38.41.png)
</Frame>

<Info>
  Client IDs for these applications can be found on the **Overview** page of each respective application. If some applications are not created yet, you can return and add them to this section after their creation.

  <Frame>
    ![Application overview showing Client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.36.39.png)
  </Frame>
</Info>

#### Application roles

To configure application roles, follow these steps:

1. Navigate to **App roles** and click **Create app role**.
2. Select **Allowed member types** select **Both (Users/Groups + Applications)**.

<Frame>
  ![Create app role form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.43.05.png)
</Frame>

3. Complete the role details with the following information:

* Display name: The name displayed for the role.
* Value: A unique identifier for the role within applications.
* Description: A description of the role’s purpose.

<Info>
  App role list should be the same as the Keycloak setup. A list of default roles can be found in the [Keycloak IAM configuration guide](./configuring-an-iam-solution).
</Info>

### Other applications registration

The following FlowX.AI applications require similar steps for registration:

* Flowx-Admin
* Flowx-Process-Engine
* Flowx-Integration-designer
* Flowx-Task-Management-Plugin
* Flowx-Scheduler-Core

***

### Flowx-Admin app registration

1. **Create a New Application Registration**
   * Go to [https://portal.azure.com](https://portal.azure.com) and log in to your Entra ID directory where you will host FlowX.AI application registrations.

2. **Register the Application**
   * Navigate to **Microsoft Entra ID > App registrations > New registration**.
   * Set the application name and select **Accounts in this organizational directory only (Single tenant)**.
   * Click **Register**. You will be redirected to the overview page of the newly created app registration.

<Info>
  You will now see the overview for your new app registration.
</Info>

#### Configure client secrets

1. Navigate to **Certificates & secrets**.
2. Under **Client secrets**, click **New client secret**.
3. Set a **description** and choose an **expiration time** for the client secret, then click **Add**.

<Frame>
  ![New client secret configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.57.31.png)
</Frame>

<Info>
  Copy the generated client secret value. This will be used to configure `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`.

  <Frame>
    ![Generated client secret value](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.59.12.png)
  </Frame>
</Info>

#### Configure API permissions

1. Go to the **API permissions** tab and click **Add a permission**.
2. Select **Microsoft Graph > Application permissions**.
3. Add the following permissions for **flowx-admin**:
   * **Application.Read.All**

<Frame>
  ![Application.Read.All permission selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.01.20.png)
</Frame>

<Info>
  If you have admin privileges, you can click **Grant admin consent** to apply these permissions. If not, contact your tenant administrator to grant consent.

  <Frame>
    ![Grant admin consent confirmation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.03.00.png)
  </Frame>
</Info>

***

### Flowx-Process-Engine app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

* **API Permissions**: No additional permissions required.

***

### Flowx-Integration-Designer app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

* **API Permissions**: No additional permissions required.

***

### Flowx-Task-Management-Plugin app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

1. Go to the **API permissions** tab and click **Add a permission**.
2. Select **Microsoft Graph > Application permissions**.
3. Add the following permissions for **flowx-task-management-plugin**:
   * **Application.Read.All**
   * **Group.Read.All**
   * **User.Read.All**

<Info>
  If you have admin privileges, you can click **Grant admin consent** to apply these permissions. If not, contact your tenant administrator to grant consent.
</Info>

***

### Flowx-Scheduler-Core app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

* **API Permissions**: No additional permissions required.

***

### Assigning a role to a user/group

To assign a role to a user or group for your FlowX.AI applications, follow these steps:

1. Go to [https://portal.azure.com](https://portal.azure.com) and log in to your Entra ID directory that hosts your FlowX.AI application registrations.

2. Navigate to **Microsoft Entra ID > Enterprise applications** and search for your **flowx-api** app registration name.\
   (An enterprise application with the same name was automatically created when the app registration was set up.)

<Frame>
  ![Enterprise applications search](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.11.43.png)
</Frame>

<Frame>
  ![Flowx-API enterprise application overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.12.51.png)
</Frame>

3. Under **Users and groups**, select **Add user/group**.

<Frame>
  ![Users and groups assignment page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.14.17.png)
</Frame>

* Choose the user or group you want to assign.

<Frame>
  ![Selecting user or group for role assignment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.16.53.png)
</Frame>

* Select the appropriate role from the available options.

4. Click **Assign** to complete the role assignment.

<Frame>
  ![Completed role assignment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.19.39.png)
</Frame>

<Info>
  It is recommended to provide roles through group membership for easier management and scalability.
</Info>

***

### Adding custom attributes

Using Microsoft Graph CLI, you can add custom attributes such as `businessFilter`.

<Tip>
  For more information about Microsoft Graph CLI, check the following docs:

  <Card title="Get started with Microsoft Graph CLI" href="https://learn.microsoft.com/en-us/graph/cli/get-started" icon="link" />
</Tip>

#### Prerequisites

* [Install the Microsoft Graph CLI](https://learn.microsoft.com/en-us/graph/cli/installation?tabs=macos).

#### Create an attribute extension property

Create an Attribute Extension Property on the flowx-api app registration:

1. Log in to Microsoft Graph CLI with the necessary permissions:

```bash theme={"system"}
   $ mgc login --scopes Directory.Read.All
```

<Tip>
  You can add additional permissions by repeating the mgc login command with the new permission scopes.
</Tip>

2. Create the attribute extension property by running the following command. Replace `<application_object_id>` with the object ID of your flowx-api application:

```bash theme={"system"}
$ mgc applications extension-properties create --application-id <application_object_id> --body '
{
  "dataType": "String",
  "name": "businessFilter",
  "targetObjects": [
    "User", "Group"
  ]
}'
```

#### Retrieve the attribute extension name

To confirm the attribute extension name, use the command below. This will output the exact name of the created extension property.

```bash theme={"system"}
$ mgc applications extension-properties list --application-id <application_object_id> --select name
```

Example output:

```json theme={"system"}
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications(\u0027<application_object_id>\u0027)/extensionProperties(name)",
  "value": [
    {
      "name": "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter"
    }
  ]
}
```

#### Configure token claim

1. Go to the **flowx-api** app registration in the Azure portal.
2. Navigate to **Token configuration**.
3. Click **Add optional claim**.
   * Select **Token type** as **Access**.
   * Check the box for `extn.businessFilter`.
4. Click Add to save the changes.

<Frame>
  ![Adding businessFilter custom claim to token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.31.05.png)
</Frame>

#### Assign attribute extension to a user

1. Log in with the required permissions to modify user attributes:

```bash theme={"system"}
$ mgc login --scopes User.ReadWrite.All
```

2. Assign the `businessFilter` attribute to a user by running the command below. Replace `<user_object_id>` with the user's `object ID`:

```bash theme={"system"}
$ mgc users patch --user-id <user_object_id> --body '
{
  "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter": "docs"
}'
```

#### Assign attribute extension to a group

Follow similar steps to assign the `businessFilter` attribute to a group. Replace `<group_object_id>` with the group’s `object ID` and use the following command:

1. Log in with the required permissions to modify group attributes:

```bash theme={"system"}
$ mgc login --scopes User.ReadWrite.All
```

2. Assign the custom attribute by  the command below, replacing `<user_object_id>` with the user’s object ID. The businessFilter attribute is set to "docs" in this example.

```bash theme={"system"}
$ mgc groups patch --group-id <group_object_id> --body '
{
  "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter": "docs"
}'
```

***

## Example JWT token for user

To verify that the custom attributes and roles have been correctly applied, you can inspect a sample JWT token issued to a user. This token will include standard claims along with any custom attributes and roles configured in your Entra ID setup.

### Steps to retrieve a JWT token

1. **Login to the FlowX.AI Application**\
   Log in to the FlowX.AI application as the user for whom the JWT token needs to be inspected.

2. **Retrieve the JWT Token**\
   After logging in, retrieve the JWT token by one of the following methods:
   * Using browser developer tools to inspect network requests (look for requests with an `Authorization` header).
   * Accessing a token endpoint if available, using a tool like Postman.

3. **Decode the JWT Token**\
   Use a JWT decoding tool, such as [jwt.io](https://jwt.io/), to decode and inspect the token.

***

### Sample JWT token structure

Below is an example JWT token structure that includes key claims, custom attributes, and roles:

<Accordion title="JWT token example">
  ```json theme={"system"}
  {
    "aud": "api://rd-p-example-flowx-api",
    "iss": "https://sts.windows.net/673cac6c-3d63-40cf-a43f-07408dd91072/",
    "iat": 1730720856,
    "nbf": 1730720856,
    "exp": 1730726397,
    "acr": "1",
    "aio": "ATQAy/8YAAAAj3ca5D/znraYUsif7RVc7TmWJPj66tqsUon0oon1xPamN1W7wN070R1JwaCwUQyQ",
    "amr": [
      "pwd"
    ],
    "appid": "673b5314-a9c8-40ec-beb5-636fa9a781b4",
    "appidacr": "0",
    "email": "john.doe@flowx.ai",
    "extn.businessFilter": [
      "docs"
    ],
    "family_name": "Doe",
    "given_name": "John",
    "groups": [
      "ef731a0d-b44f-44da-bd78-67363c901bb1",
      "db856713-0dfa-4d3d-aefa-bbb598257084",
      "4336202b-6fc4-4132-afab-7f6573993325",
      "5dc0b52e-823b-4ce9-b3e4-b3070912a4ef",
      "ce006d40-555f-4247-890b-1053fa3cb172",
      "291ac248-4e29-4c91-8e1d-19cbeec64eb8",
      "b82dc551-f3f0-4d28-aaf0-a0a74fe3b3e3",
      "42b39b5f-7545-48be-88d1-6e88716236db",
      "cc0f776a-1cb2-4b8c-a472-8e1393764442",
      "6eac9487-e04c-41e6-81ce-364f09c22bbf",
      "01c30789-6862-4085-b5c4-f0cb02fb41b0",
      "75ac188b-61c4-4aa9-ad7e-af1d543e199a",
      "e726fda5-79f0-440b-b86c-8a9820d14d2e",
      "259980bb-e881-4d93-9912-d2562441a257",
      "9146edd4-6194-4487-b524-79956635f514",
      "ce046ce2-6ef8-40f2-9f4e-a70f1ca14ecf",
      "62d1f9f5-858c-43e2-af92-94bcc575681b",
      "69df5ff6-1da9-49d1-9871-b7e62de2b212",
      "043d25fc-a507-47ee-83e3-1d31ce0d9b35"
    ],
    "ipaddr": "86.126.6.183",
    "name": "Jonh Doe",
    "oid": "61159071-3fd6-4373-8aec-77ee58675776",
    "preferred_username": "john.doe@flowx.ai",
    "rh": "1.AYEAbKw8Z2M9z0CkPwdAjdkQckKVleyLibxCtpIufT-d8oKBAAeBAA.",
    {/* Most `ROLE_*` entries below are legacy realm roles that may exist in realms created from older FlowX realm exports. FlowX 5.x services do not evaluate them — Designer and platform access is governed by workspace and organization roles plus permissions; see the [Complete roles & permissions matrix](./roles-permissions-matrix). Realm roles are only evaluated where your own configuration references them (for example, swimlane access rules). */}
    "roles": [
      "ROLE_DOCUMENT_TEMPLATES_IMPORT",
      "FLOWX_ROLE",
      "ROLE_TASK_MANAGER_OOO_ADMIN",
      "ROLE_ADMIN_MANAGE_CONFIG_IMPORT",
      "ROLE_INTEGRATION_SYSTEM_READ",
      "ROLE_INTEGRATION_WORKFLOW_READ_RESTRICTED",
      "ROLE_ADMIN_MANAGE_PROCESS_ADMIN",
      "ROLE_MANAGE_NOTIFICATIONS_ADMIN",
      "ROLE_ADMIN_MANAGE_INTEGRATIONS_EDIT",
      "ROLE_TASK_MANAGER_HOOKS_IMPORT",
      "ROLE_THEMES_READ",
      "ROLE_ENGINE_MANAGE_PROCESS_EDIT",
      "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_ADMIN",
      "ROLE_AI_OPTIMIZER_EDIT",
      "ROLE_ENGINE_MANAGE_INSTANCE_READ",
      "ROLE_ADMIN_MANAGE_INTEGRATIONS_ADMIN",
      "ROLE_ADMIN_MANAGE_PROCESS_IMPORT",
      "ROLE_COPO_TELLER",
      "ROLE_CMS_CONTENT_READ",
      "ROLE_CMS_CONTENT_IMPORT",
      "ROLE_INTEGRATION_WORKFLOW_ADMIN",
      "ROLE_AI_ARCHITECT_EDIT",
      "ROLE_TASK_MANAGER_HOOKS_READ",
      "ROLE_AI_WRITER_EDIT",
      "ROLE_TASK_MANAGER_HOOKS_ADMIN",
      "ROLE_MEDIA_LIBRARY_EDIT",
      "ROLE_CMS_TAXONOMIES_READ",
      "ROLE_AI_INSPECTOR_EDIT",
      "FLOWX_FRONTOFFICE",
      "ROLE_START_EXTERNAL",
      "ROLE_DOCUMENT_TEMPLATES_READ",
      "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_IMPORT",
      "VIEW_INSTANCES",
      "ROLE_ADMIN_MANAGE_INTEGRATIONS_IMPORT",
      "ROLE_ADMIN_MANAGE_USERS_READ",
      "ROLE_THEMES_ADMIN",
      "ROLE_ADMIN_MANAGE_PLATFORM_READ",
      "ROLE_TASK_MANAGER_OOO_EDIT",
      "ROLE_CMS_TAXONOMIES_EDIT",
      "ROLE_THEMES_IMPORT",
      "ROLE_AI_DEVELOPER_EDIT",
      "ROLE_MANAGE_NOTIFICATIONS_READ",
      "ROLE_INTEGRATION_SYSTEM_EDIT",
      "ROLE_MANAGE_NOTIFICATIONS_SEND",
      "FLOWX_ADMIN",
      "ROLE_INTEGRATION_READ",
      "FLOWX_BACKOFFICE",
      "ROLE_DOCUMENT_TEMPLATES_EDIT",
      "ROLE_MEDIA_LIBRARY_IMPORT",
      "ROLE_AI_ASSISTANT_READ",
      "ROLE_ADMIN_MANAGE_CONFIG_EDIT",
      "ROLE_CMS_TAXONOMIES_IMPORT",
      "ROLE_ADMIN_MANAGE_CONFIG_ADMIN",
      "ROLE_TASK_MANAGER_TASKS_READ",
      "ROLE_DOCUMENT_TEMPLATES_ADMIN",
      "ROLE_INTEGRATION_WORKFLOW_READ",
      "ROLE_COPO_VIEWER",
      "ROLE_MEDIA_LIBRARY_ADMIN",
      "ROLE_NOTIFICATION_TEMPLATES_EDIT",
      "ROLE_ADMIN_MANAGE_PROCESS_READ",
      "ROLE_AI_INTEGRATOR_EDIT",
      "ROLE_AI_SUPERVISOR_EDIT",
      "ROLE_INTEGRATION_WORKFLOW_EDIT",
      "ROLE_CMS_CONTENT_ADMIN",
      "ROLE_CMS_CONTENT_EDIT",
      "FLOWX_SUPERVISOR",
      "ROLE_ADMIN_MANAGE_CONFIG_READ",
      "ROLE_TASK_MANAGER_OOO_READ",
      "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_EDIT",
      "ROLE_INTEGRATION_ADMIN",
      "ROLE_NOTIFICATION_TEMPLATES_READ",
      "ROLE_AI_AUDITOR_EDIT",
      "ROLE_ENGINE_MANAGE_INSTANCE_ADMIN",
      "ROLE_INTEGRATION_SYSTEM_ADMIN",
      "ROLE_ADMIN_MANAGE_PROCESS_EDIT",
      "ROLE_INTEGRATION_EDIT",
      "ROLE_AI_DESIGNER_EDIT",
      "ROLE_TASK_MANAGER_HOOKS_EDIT",
      "ROLE_AI_COMMAND_READ",
      "ROLE_CMS_TAXONOMIES_ADMIN",
      "ROLE_ADMIN_MANAGE_USERS_ADMIN",
      "ROLE_AI_ANALYST_EDIT",
      "ROLE_TASK_MANAGER_VIEWS_ADMIN",
      "ROLE_ADMIN_MANAGE_PLATFORM_ADMIN",
      "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_READ",
      "ROLE_AI_STRATEGIST_EDIT",
      "ROLE_THEMES_EDIT",
      "ROLE_NOTIFICATION_TEMPLATES_ADMIN",
      "ROLE_INTEGRATION_IMPORT",
      "ROLE_NOTIFICATION_TEMPLATES_IMPORT",
      "ROLE_ADMIN_MANAGE_INTEGRATIONS_READ",
      "ROLE_ADMIN_MANAGE_USERS_EDIT",
      "ROLE_MEDIA_LIBRARY_READ"
    ],
    "scp": "FlowxAI.ReadWrite.All",
    "sub": "tMG9A1npM9hK89AV9rdUvTAKVlli3oLkyI1E8F7bV5Y",
    "tid": "673cac6c-3d63-40cf-a43f-07408dd91072",
    "unique_name": "john.doe@flowx.ai",
    "upn": "john.doe@flowx.ai",
    "uti": "v3igRE_kEUqZC4nbXII3AA",
    "ver": "1.0",
    "wids": [
      "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
      "fe930be7-5e62-47db-91af-98c3a49a38b1",
      "e3973bdf-4987-49ae-837a-ba8e231c7286",
      "158c047a-c907-4556-b7ef-446551a6b5f7",
      "e8611ab8-c189-46e8-94e1-60213ab1f814",
      "b79fbf4d-3ef9-4689-8143-76b194e85509"
    ]
  }
  ```
</Accordion>

## Configure helm charts

This section provides details on configuring Helm charts for FlowX.AI applications, including where to retrieve required values and setting environment variables for different application components.

***

### Where to get the values

* **tenant\_id**: The unique identifier for your Entra ID tenant.

  ![Tenant ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%286%29.png)

* **client\_id**: The client ID for the specific FlowX.AI application.

  ![Client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%287%29.png)

* **client\_secret**: The client secret generated during app registration (only visible at creation).

  ![Client Secret](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%288%29.png)

***

### Helm chart values

These configurations are required for different FlowX.AI application components. Substitute `<tenant_id>`, `<flowx_web_client_id>`, and `<client_id>` with your specific values.

***

#### Designer

For the Designer component, use the following settings:

```yaml theme={"system"}
SKIP_ISSUER_CHECK: true
STRICT_DISCOVERY_DOCUMENT_VALIDATION: false
KEYCLOAK_ISSUER: https://login.microsoftonline.com/<tenant_id>/v2.0
KEYCLOAK_CLIENT_ID: <flowx_web_client_id>
KEYCLOAK_SCOPES: "openid profile email offline_access api://rd-e-example-flowx-api/FlowxAI.ReadWrite.All"
KEYCLOAK_REDIRECT_URI: https://flowx.example.az1.cloud.flowxai.dev
```

#### All Java application

```yaml theme={"system"}
SECURITY_TYPE: jwt-public-key
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI: https://sts.windows.net/<tenant_id>/
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI: https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys
```

#### Java applications with a Service Principal

These settings apply to Java applications that require a service principal, such as Admin, Integration Designer, Process Engine, Scheduler Core, and Task Management Plugin.

```yaml theme={"system"}
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID: <client_id>
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: <client_secret>
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_SCOPE: api://rd-p-example-flowx-api/.default
```

#### Java applications with access to Microsoft Graph API

The following configuration is required for Java applications that need access to the Microsoft Graph API, such as Admin and Task Management Plugin.

```yaml theme={"system"}
OPENID_PROVIDER: entra
OPENID_ENTRA_TENANT_ID: <tenant_id>
OPENID_ENTRA_PRINCIPAL_ID: <flowx_admin_client_id>
```


# End-user access management
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/end-user-access-management

Manage end-user roles, groups, and attributes for controlling access to published solutions at runtime.

<Info>
  **5.8.0+: assignment model changed.** Up to 5.7.0, a role assigned to a user or group at organization level granted access on every project that listed the role. Starting with 5.8.0, role assignment is **per-solution**: define roles and groups here at organization level, then assign them to users or groups from the **Share** modal on the Solutions page. End-user groups also moved from Keycloak to FlowX. See [Runtime authorization](./runtime-authorization) for the new model.
</Info>

## Overview

End-user access management lets organization admins control who can access published solutions at runtime. Unlike Designer users (who build processes and workflows), end users interact with the finished solutions through the container app.

Manage end users from **Organization Settings** → **Access Management**, where three sections handle runtime access:

* **End-Users**: Invite and manage users who access solutions
* **End-Users Roles**: Define roles that control what end users can access
* **End-Users Groups**: Organize users into groups with role assignments and custom attributes

***

## End-users

View and manage the list of end users in your organization. End users are separate from Designer users. They access published solutions but cannot modify processes or workflows.

To invite an end user:

1. Navigate to **Organization Settings** → **Access Management** → **End-Users**
2. Click **Add** to invite a new user
3. Enter the user's details

<Info>
  End users authenticate through the same Keycloak realm as the organization. SMTP must be configured in Keycloak for invitation emails to be sent.
</Info>

***

## End-users roles

Roles define what end users can access at runtime. Each role has a name and description. Roles are assigned to users through groups.

### Managing roles

<Steps>
  <Step title="Navigate to End-Users Roles">
    Go to **Organization Settings** → **Access Management** → **End-Users Roles**.
  </Step>

  <Step title="Create a role">
    Click **Add new**, enter a **Name** and optional **Description**, then click **Save**.
  </Step>

  <Step title="Assign roles to processes">
    In a project's version settings, assign which roles can access specific processes via the **Permissions** tab.
  </Step>
</Steps>

Roles can be edited or deleted from the roles list. Deleting a role removes it from all groups and process permissions where it was assigned.

***

## End-users groups

Groups organize end users and assign them roles and custom attributes. A group can have multiple roles and multiple key-value attributes.

### Managing groups

<Steps>
  <Step title="Navigate to End-Users Groups">
    Go to **Organization Settings** → **Access Management** → **End-Users Groups**.
  </Step>

  <Step title="Create a group">
    Click **Add new** and configure:

    | Field          | Description                                                              |
    | -------------- | ------------------------------------------------------------------------ |
    | **Name**       | Group name (alphanumeric, dashes, underscores, spaces)                   |
    | **Roles**      | Select one or more end-user roles to assign to all members of this group |
    | **Attributes** | Optional key-value pairs for custom metadata (e.g., department, region)  |
  </Step>

  <Step title="Add attributes (optional)">
    Click **Add attribute** to add custom key-value pairs. Each attribute has a **Key** and one or more comma-separated **Values**. Attributes can be used for business filters and data-driven access control.
  </Step>
</Steps>

***

## Permissions

| Permission                 | Description                              |
| -------------------------- | ---------------------------------------- |
| `org_runtime_users_read`   | View the end-users list                  |
| `org_runtime_users_write`  | Invite and manage end users              |
| `org_runtime_roles_read`   | View end-user roles                      |
| `org_runtime_roles_write`  | Create, edit, and delete end-user roles  |
| `org_runtime_groups_read`  | View end-user groups                     |
| `org_runtime_groups_write` | Create, edit, and delete end-user groups |

These permissions are available to **Organization Admin** and **Organization Owner** roles.

***

## Related resources

<CardGroup>
  <Card title="Organization settings" icon="gear" href="/5.9/docs/saas/organization-settings">
    Overview of all organization-level settings
  </Card>

  <Card title="Roles and permissions matrix" icon="table" href="./roles-permissions-matrix">
    Complete reference for all platform roles and permissions
  </Card>

  <Card title="Swimlanes" icon="arrows-left-right" href="/5.9/docs/platform-deep-dive/user-roles-management/swimlanes">
    Configure role-based task assignment in processes
  </Card>

  <Card title="Business filters" icon="filter" href="/5.9/docs/platform-deep-dive/user-roles-management/business-filters">
    Filter data visibility based on user roles and attributes
  </Card>
</CardGroup>


# Permission reference guide
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/permission-reference-guide

Technical reference for FlowX Designer permissions, naming conventions, and UI mappings

<Note>
  **Documentation Navigation:**

  * [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) - Role overview and concepts
  * [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) - Detailed permission specifications
  * **Permission Reference Guide** (Current) - Technical implementation details
  * [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide) - Practical scenarios and best practices
</Note>

<Info>
  This guide provides technical reference information for FlowX Designer permissions, including naming conventions, UI element mappings, and implementation details. Use this guide when you need to understand how permissions work at a technical level.
</Info>

## Permission naming conventions

### Naming structure

FlowX permissions follow a consistent naming pattern that helps identify scope and purpose:

```
[scope_prefix]_[resource]_[operation]
```

### Scope prefixes

| Prefix   | Scope Level       | Example Permissions                                        | Usage                                                                             |
| -------- | ----------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `org_`   | Organization      | `org_admin`                                                | Cross-workspace administration and system-level operations                        |
| `wks_`   | Workspace         | `wks_users_read` • `wks_builds_create` • `wks_font_delete` | Workspace-level resources that apply across all projects in the workspace         |
| `proj_`  | Project           | `proj_mediafile_read` • `proj_data_type_edit`              | Project-specific resources when disambiguation from workspace resources is needed |
| *(none)* | Context-dependent | `process_read` • `workflow_edit` • `enum_create`           | Project-level resources where context is clear from usage                         |

<Note>
  **Why some project permissions lack the `proj_` prefix:**

  Most project-level configuration resources (processes, workflows, enumerations, etc.) don't use the `proj_` prefix because:

  * Their context is always project-scoped
  * There's no workspace-level equivalent that would create naming conflicts
  * Shorter names improve readability

  The `proj_` prefix is used when:

  * A workspace-level equivalent exists (e.g., `proj_mediafile_*` vs `mediafile_*` for workspace media)
  * Disambiguation is necessary (e.g., `proj_data_type_*` for project data model)
</Note>

### Operation suffixes

| Suffix    | Description              | Typical Actions                                                  | Example Permissions                                                      |
| --------- | ------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `_read`   | View and access resource | • View lists • See details • Export data • Access audit logs     | `process_read` • `wks_users_read` • `theme_read`                         |
| `_edit`   | Modify existing resource | • Update properties • Change configurations • Save modifications | `workflow_edit` • `wks_active_policy_edit` • `enum_edit`                 |
| `_create` | Create new instances     | • Add new items • Import data • Duplicate existing items         | `project_create` • `wks_builds_create` • `notification_templates_create` |
| `_delete` | Remove resource          | • Delete items • Remove from system                              | `stage_delete` • `wks_groups_delete` • `process_delete`                  |
| `_admin`  | Administrative control   | • Grant/revoke access • Manage permissions • Full governance     | `projects_admin` • `org_admin`                                           |

### Special naming cases

<AccordionGroup>
  <Accordion title="Properties named 'id' or 'url'" icon="tag">
    When a resource property is named "id" or "url" (case insensitive), it must be prefixed with `userDefined:` to avoid conflicts with system properties.

    **Examples:**

    * `userDefined:URL` - For a custom URL property
    * `userDefined:id` - For a custom ID field

    This applies when working with:

    * Database properties
    * Configuration parameters
    * Custom data model fields
  </Accordion>

  <Accordion title="Date and place properties" icon="calendar">
    **Date Properties** are split into multiple permission fields:

    ```
    date:`{property_name}`:start
    date:`{property_name}`:end (optional)
    date:`{property_name}`:is_datetime (0 or 1)
    ```

    **Place Properties** are split into multiple fields:

    ```
    place:`{property_name}`:name
    place:`{property_name}`:address
    place:`{property_name}`:latitude
    place:`{property_name}`:longitude
    place:`{property_name}`:google_place_id (optional)
    ```

    These expanded formats provide granular control over complex property types.
  </Accordion>

  <Accordion title="Checkbox property values" icon="square-check">
    Checkbox properties use special string values instead of boolean:

    * `__YES__` for checked
    * `__NO__` for unchecked

    **Example:**

    ```json theme={"system"}
    {
      "Is Complete": "__YES__",
      "Requires Approval": "__NO__"
    }
    ```
  </Accordion>

  <Accordion title="Number property format" icon="hashtag">
    Number properties must use JavaScript number format, not strings:

    **Correct:**

    ```json theme={"system"}
    {"Priority": 5}
    ```

    **Incorrect:**

    ```json theme={"system"}
    {"Priority": "5"}
    ```
  </Accordion>

  <Accordion title="Substitution tags consolidation" icon="tags">
    Substitution tags use the enumeration permission set:

    * `enum_read`
    * `enum_edit`
    * `enum_create`
    * `enum_delete`

    There are no separate `substitution_tags_*` permissions - enumeration permissions cover both resource types.
  </Accordion>

  <Accordion title="AI agent permissions" icon="robot">
    AI agent permissions deviate from the standard pattern:

    * Only `aiagent_edit` exists
    * No separate `_read`, `_create`, or `_delete` permissions
    * The edit permission grants access to all AI agent functionality (developer, analyst, designer)
  </Accordion>
</AccordionGroup>

### Permission examples by category

<Tabs>
  <Tab title="Organization Level">
    | Permission  | Scope        | Resource       | Operation       |
    | ----------- | ------------ | -------------- | --------------- |
    | `org_admin` | Organization | Administration | Admin (special) |

    <Note>
      Organization-level permissions are limited. Most administration occurs at workspace level.
    </Note>
  </Tab>

  <Tab title="Workspace Level">
    | Permission                            | Scope     | Resource                                                                                       | Operation |
    | ------------------------------------- | --------- | ---------------------------------------------------------------------------------------------- | --------- |
    | `wks_users_read`                      | Workspace | Users                                                                                          | Read      |
    | `wks_users_create`                    | Workspace | Users                                                                                          | Create    |
    | `wks_groups_edit`                     | Workspace | Groups                                                                                         | Edit      |
    | `wks_roles_delete`                    | Workspace | Roles                                                                                          | Delete    |
    | `wks_builds_create`                   | Workspace | Builds                                                                                         | Create    |
    | `wks_active_policy_edit`              | Workspace | Active Policy                                                                                  | Edit      |
    | `wks_config_param_overrides_read`     | Workspace | Config Param Overrides                                                                         | Read      |
    | `wks_process_instances_edit`          | Workspace | Process Instances                                                                              | Edit      |
    | `wks_process_instance_variables_edit` | Workspace | Process Variables                                                                              | Edit      |
    | `wks_platform_status_read`            | Workspace | Platform Status                                                                                | Read      |
    | `wks_env_info_edit` ⚠️                | Workspace | Environment Info ⚠️ *Deprecated in 5.7.0; the Configure Environment Info UI has been removed.* | Edit      |
    | `wks_audit_log_read`                  | Workspace | Audit Log                                                                                      | Read      |
    | `mediafile_create`                    | Workspace | Media Files                                                                                    | Create    |
    | `theme_edit`                          | Workspace | Themes                                                                                         | Edit      |
    | `wks_font_delete`                     | Workspace | Fonts                                                                                          | Delete    |
    | `proxy_connection_read`               | Workspace | Proxy Connections                                                                              | Read      |
    | `proxy_connection_edit`               | Workspace | Proxy Connections                                                                              | Edit      |
    | `proxy_connection_create`             | Workspace | Proxy Connections                                                                              | Create    |
    | `proxy_connection_delete`             | Workspace | Proxy Connections                                                                              | Delete    |
  </Tab>

  <Tab title="Project Level">
    | Permission                      | Scope   | Resource                | Operation       |
    | ------------------------------- | ------- | ----------------------- | --------------- |
    | `project_read`                  | Project | Project/Library         | Read            |
    | `project_owner`                 | Project | Project/Library         | Owner (special) |
    | `projects_admin`                | Project | Projects                | Admin           |
    | `process_edit`                  | Project | Processes               | Edit            |
    | `proj_data_type_create`         | Project | Data Model              | Create          |
    | `enum_delete`                   | Project | Enumerations            | Delete          |
    | `proj_mediafile_read`           | Project | Media Library           | Read            |
    | `notification_templates_create` | Project | Notification Templates  | Create          |
    | `document_templates_edit`       | Project | Document Templates      | Edit            |
    | `task_view_read`                | Project | Views                   | Read            |
    | `stage_create`                  | Project | Stages                  | Create          |
    | `allocation_rule_edit`          | Project | Allocation Rules        | Edit            |
    | `data_source_delete`            | Project | Data Sources            | Delete          |
    | `workflow_read`                 | Project | Workflows               | Read            |
    | `reusable_ui_create`            | Project | Reusable UI             | Create          |
    | `reusable_br_edit`              | Project | Reusable Business Rules | Edit            |
    | `dependency_read`               | Project | Dependencies            | Read            |
    | `config_param_create`           | Project | Config Parameters       | Create          |
    | `version_edit`                  | Project | Version Settings        | Edit            |
    | `aiagent_edit`                  | Project | AI Agents               | Edit (special)  |
  </Tab>
</Tabs>

## Permission-to-UI action mapping

<Info>
  This section shows how permissions control specific UI elements and actions in FlowX Designer. When a user lacks a permission, the corresponding UI element is hidden or disabled.
</Info>

### Understanding UI behavior

<Card title="Permission Enforcement Rules" icon="shield-halved">
  **Read Permission Behavior:**

  * Read permission must be explicitly declared
  * Not automatically implied by other permissions
  * Exception: `workspace_read` is auto-included with any workspace permission

  **UI Display Rules:**

  * Missing permission = Hidden UI element
  * Read-only permission = View mode with disabled controls
  * No error messages shown for hidden elements
</Card>

### Workspace level permissions

<Tabs>
  <Tab title="Themes">
    #### Theme Permissions (`theme_*`)

    | Permission     | UI Actions Enabled                                                                           | UI Elements                                                                                                                    |
    | -------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | `theme_read`   | • View themes • Export theme                                                                 | • Theme entry in main menu • Theme list in read-only mode • Export button                                                      |
    | `theme_edit`   | • Modify theme settings • Set as default • Configure theme sections • Copy from other themes | • Configure in contextual menu • Set as default button • Save button • All edit controls in theme sections • Copy from actions |
    | `theme_create` | • Create new theme • Import theme • Duplicate existing theme                                 | • Add button • Import action • Duplicate in contextual menu                                                                    |
    | `theme_delete` | • Remove theme                                                                               | • Delete in contextual menu                                                                                                    |

    <Note>
      When user has only `theme_read`, the theme page displays in read-only mode with all edit controls disabled.
    </Note>
  </Tab>

  <Tab title="Fonts">
    #### Font Permissions (`wks_font_*`)

    | Permission        | UI Actions Enabled                        | UI Elements                                                               |
    | ----------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
    | `wks_font_read`   | • View font list • Export fonts           | • Fonts entry in main menu • Font list in read-only mode • Export actions |
    | `wks_font_create` | • Upload new fonts • Import font packages | • Add button • Import action                                              |
    | `wks_font_delete` | • Remove fonts                            | • Delete icon in contextual menu                                          |

    <Note>
      Font editing is implicit with create permission - fonts are replaced rather than edited.
    </Note>
  </Tab>

  <Tab title="Media Library">
    #### Media Library Permissions (`mediafile_*`)

    | Permission         | UI Actions Enabled                            | UI Elements                                                                              |
    | ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
    | `mediafile_read`   | • View media assets • Export media files      | • Global media library entry in main menu • Media list in read-only mode • Export button |
    | `mediafile_edit`   | • Update media metadata • Replace media files | • Edit controls for media properties                                                     |
    | `mediafile_create` | • Upload new media • Import media packages    | • Add button • Import action                                                             |
    | `mediafile_delete` | • Remove media files                          | • Delete in contextual menu                                                              |
  </Tab>

  <Tab title="Users & Groups">
    #### User Management Permissions (`wks_users_*`)

    | Permission         | UI Actions Enabled                                 | UI Elements                                              |
    | ------------------ | -------------------------------------------------- | -------------------------------------------------------- |
    | `wks_users_read`   | • View workspace users • See user details          | • Users entry in main menu • User list in read-only mode |
    | `wks_users_edit`   | • Modify user workspace access • Update user roles | • Edit controls for user properties                      |
    | `wks_users_create` | • Add users to workspace • Grant workspace access  | • Add button • Grant access action                       |
    | `wks_users_delete` | • Remove workspace access                          | • Delete in contextual menu                              |

    #### Group Management Permissions (`wks_groups_*`)

    | Permission          | UI Actions Enabled                                  | UI Elements                                                |
    | ------------------- | --------------------------------------------------- | ---------------------------------------------------------- |
    | `wks_groups_read`   | • View workspace groups • See group members         | • Groups entry in main menu • Group list in read-only mode |
    | `wks_groups_edit`   | • Modify group membership • Update group properties | • Edit controls for groups • Add/remove member actions     |
    | `wks_groups_create` | • Create new groups                                 | • Add button                                               |
    | `wks_groups_delete` | • Remove groups                                     | • Delete in contextual menu                                |

    #### Role Management Permissions (`wks_roles_*`)

    | Permission         | UI Actions Enabled                                 | UI Elements                                              |
    | ------------------ | -------------------------------------------------- | -------------------------------------------------------- |
    | `wks_roles_read`   | • View workspace roles • See role permissions      | • Roles entry in main menu • Role list in read-only mode |
    | `wks_roles_edit`   | • Modify role permissions • Update role properties | • Edit controls for roles • Permission checkboxes        |
    | `wks_roles_create` | • Create custom roles • Duplicate existing roles   | • Add button • Duplicate action                          |
    | `wks_roles_delete` | • Remove custom roles                              | • Delete in contextual menu                              |

    <Warning>
      Predefined roles (`workspace_admin`, `workspace_user`, etc.) cannot be edited or deleted regardless of permissions.
    </Warning>
  </Tab>

  <Tab title="Runtime Operations">
    #### Build Permissions (`wks_builds_*`)

    | Permission          | UI Actions Enabled                                    | UI Elements                                                     |
    | ------------------- | ----------------------------------------------------- | --------------------------------------------------------------- |
    | `wks_builds_read`   | • View all workspace builds • See build details       | • Runtime > Builds menu entry • Build list for all libraries    |
    | `wks_builds_create` | • Import build packages • Create builds from versions | • Import build button • Create build action on library versions |

    <Note>
      `wks_builds_read` allows viewing builds from **all** libraries in the workspace, not just accessible projects.
    </Note>

    #### Active Policy Permissions (`wks_active_policy_*`)

    | Permission               | UI Actions Enabled                                                     | UI Elements                                                                                                                               |
    | ------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | `wks_active_policy_read` | • View active policies • See policy configurations • Access audit logs | • Active policy entry in Runtime tab • Policy page in read-only mode • Type and branch selectors disabled • Audit logs in contextual menu |
    | `wks_active_policy_edit` | • Select branch/build • Update active policy • Change policy type      | • Save button enabled • Branch/build dropdown selectors enabled • Policy type selector enabled                                            |

    #### Configuration Parameter Overrides (`wks_config_param_overrides_*`)

    | Permission                          | UI Actions Enabled                                                   | UI Elements                                                                                                                          |
    | ----------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
    | `wks_config_param_overrides_read`   | • View parameter overrides • See override values • Access audit logs | • Configuration parameters overrides menu entry • Override list in read-only mode • View icon on rows • Audit log in contextual menu |
    | `wks_config_param_overrides_create` | • Add new overrides                                                  | • Add configuration parameter override button                                                                                        |
    | `wks_config_param_overrides_edit`   | • Modify override values                                             | • Edit icon on table rows • Update override modal                                                                                    |
    | `wks_config_param_overrides_delete` | • Remove overrides                                                   | • Delete in contextual menu                                                                                                          |

    #### Process Variables (`wks_process_instance_variables_edit`)

    | Permission                            | UI Actions Enabled                                                           | UI Elements                                                                                                    |
    | ------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
    | `wks_process_instance_variables_edit` | • Edit process variables on active instances • Add/delete attributes/objects | • Edit option in contextual menu • Edit button in Variables tab • Monaco editor for JSON editing • Save button |

    <Note>
      This permission is currently assigned to `ORG_ADMIN` and `WORKSPACE_ADMIN` roles. A dedicated role will be created for this permission in future releases.
    </Note>
  </Tab>
</Tabs>

### Project level permissions

<Tabs>
  <Tab title="Project Management">
    #### Project Permissions (`project_*`)

    | Permission       | UI Actions Enabled                                             | UI Elements                                                                                                                |
    | ---------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `project_read`   | • View project details • Copy project UUID • Access audit logs | • Configure (shown as "View") in contextual menu • Copy UUID action • Audit log access • Project details in read-only mode |
    | `project_edit`   | • Modify project settings • Configure project properties       | • Configure in contextual menu • Edit controls enabled • Save button active                                                |
    | `project_create` | • Create new projects • Import project versions                | • Add button • Import version action                                                                                       |
    | `project_delete` | • Remove projects                                              | • Delete in contextual menu                                                                                                |

    <Warning>
      `project_create` is granted at workspace level. Users create projects within their workspace, not within other projects.
    </Warning>
  </Tab>

  <Tab title="Process Configuration">
    #### Process Permissions (`process_*`)

    | Permission       | UI Actions Enabled                                                                             | UI Elements                                                                                                                                            |
    | ---------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `process_read`   | • View process list • Export processes • Copy to another project • Access audit logs           | • Processes list • Export all button • Export in contextual menu • Copy to another project/library action • Audit logs access • Read-only process view |
    | `process_edit`   | • Modify process definitions • Configure process details • Edit process settings • Clear cache | • Configure details in contextual menu • Edit settings action • Save button • All edit controls on process designer • Clear cache action               |
    | `process_create` | • Create new processes • Import processes • Duplicate processes                                | • Add button • Import from ZIP (bulk) • Duplicate in contextual menu                                                                                   |
    | `process_delete` | • Remove processes                                                                             | • Delete in contextual menu                                                                                                                            |

    <Note>
      When user has only `process_read`, the process designer opens in read-only mode with all edit controls disabled.
    </Note>
  </Tab>

  <Tab title="Content Management">
    #### Enumeration Permissions (`enum_*`)

    | Permission    | UI Actions Enabled                                                                                         | UI Elements                                                                                                                                                                              |
    | ------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `enum_read`   | • View enumerations • Export enumerations • See enum values                                                | • Enumerations entry in Project menu • Export to ZIP button • Export to CSV button • Read icon on enum rows • Read-only enum view                                                        |
    | `enum_edit`   | • Modify enum values • Configure enum settings • Add enum values • Create child enums • Remove enum values | • Edit icon on enum rows (replaces read icon) • Configure in contextual menu • Edit icon on enum value rows • Create child enum icon • Delete icon on enum value rows • Add value button |
    | `enum_create` | • Create new enumerations • Import enumerations • Duplicate enumerations                                   | • Add button • Import from ZIP • Import from CSV • Duplicate in contextual menu                                                                                                          |
    | `enum_delete` | • Remove enumerations                                                                                      | • Delete in contextual menu                                                                                                                                                              |

    <Note>
      The read icon automatically changes to an edit icon when the user has `enum_edit` permission.
    </Note>
  </Tab>

  <Tab title="Workflows">
    #### Workflow Permissions (`workflow_*`)

    | Permission        | UI Actions Enabled                                                                                                                       | UI Elements                                                                                                                                                                                                |
    | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `workflow_read`   | • View workflows • Export workflows                                                                                                      | • Workflows entry in Project menu • Export all (bulk) • Export in contextual menu                                                                                                                          |
    | `workflow_edit`   | • Modify workflow logic • Configure workflow settings • Edit workflow details • Clear cache • Delete condition nodes • Save code changes | • Configure in contextual menu • Edit details in resource page contextual menu • Clear cache in resource page contextual menu • Delete icon on Condition type nodes • Save changes in expanded code editor |
    | `workflow_create` | • Create new workflows • Import workflows • Duplicate workflows                                                                          | • Add button • Import from ZIP • Duplicate in contextual menu • Duplicate in resource page contextual menu                                                                                                 |
    | `workflow_delete` | • Remove workflows                                                                                                                       | • Delete in contextual menu                                                                                                                                                                                |
  </Tab>
</Tabs>

### Permission dependency rules

<Card title="Critical Permission Dependencies" icon="link">
  **Workspace Level:**

  `workspace_read` - Automatically included when any other workspace permission is granted. Required for basic workspace visibility and validation.

  `workspace_edit` - Should be included when granting any workspace edit permission. Provides general workspace modification context.

  **Project Level:**

  `project_read` - Automatically sent to backend when any project-level permission is selected, even though not displayed in UI as selectable. Required for basic project access validation.

  **Rule:** Read permissions establish the foundation for all other permissions on a resource.
</Card>

## Groups technical reference

<Info>
  Understanding how groups work at a technical level helps administrators implement effective access control strategies.
</Info>

### System-managed groups

#### Everyone in workspace group

<Card title="Technical Implementation" icon="code">
  **Group Identifier:** `all_users_[workspace_name]`

  **Display Name:** `Everyone from <workspace name>`

  **Automatic Behaviors:**

  * Created during workspace provisioning via database trigger
  * Membership managed through workspace access events
  * Cannot be manually modified via UI or API
  * Pre-populated in project access grant interfaces
  * Included in user/group search result sets

  **Database Relationships:**

  ```
  workspace (1) ←→ (1) all_users_group
  user (N) ←→ (M) workspace_access
  workspace_access → triggers → all_users_group_membership
  ```

  **Use Cases:**

  * Default access patterns for new projects
  * Workspace-wide policy application
  * Bulk access management operations
  * Simplified onboarding workflows
</Card>

### Custom group architecture

<Tabs>
  <Tab title="Group Structure">
    **Group Properties:**

    * Unique identifier (UUID)
    * Display name (user-defined)
    * Description (optional)
    * Workspace scope (cannot span workspaces)
    * Member list (user IDs)
    * Role assignments (workspace-level)

    **Group Membership:**

    * Direct user assignments
    * No nested group support
    * Membership changes propagate immediately
    * Audit trail maintained for membership changes
  </Tab>

  <Tab title="Permission Resolution">
    **When user has multiple group memberships:**

    1. Collect all permissions from all groups
    2. Union permissions (more permissive wins)
    3. Combine with individual user permissions
    4. Apply most permissive result

    **Example:**

    ```
    User is member of:
    - Group A: project_viewer on Project X
    - Group B: project_editor on Project X

    Result: User has project_editor access (more permissive)
    ```

    **Individual Override:**
    Individual permission assignments take precedence over group-based assignments when more restrictive.
  </Tab>

  <Tab title="Performance Considerations">
    **Optimization Strategies:**

    * Group permissions cached per user session
    * Membership changes invalidate affected user caches
    * Batch operations recommended for large groups
    * Avoid excessive group count per user (recommend \< 20)

    **Best Practices:**

    * Use groups for >5 users with same access pattern
    * Prefer groups over individual assignments at scale
    * Regular cleanup of unused groups
    * Monitor group membership sizes
  </Tab>
</Tabs>

## Advanced topics

### Permission override scenarios

<AccordionGroup>
  <Accordion title="Multiple Role Assignments" icon="layer-group">
    **Scenario:** User assigned multiple roles at same level

    **Resolution:**

    * Permissions are combined (union)
    * Most permissive permission wins
    * Cannot have conflicting restrictions

    **Example:**

    ```
    User has both:
    - theme_editor (theme permissions)
    - workspace_runtime_editor (runtime permissions)

    Result: User has both theme AND runtime permissions
    ```
  </Accordion>

  <Accordion title="Cross-Level Permission Conflicts" icon="triangle-exclamation">
    **Scenario:** Workspace role vs. project role

    **Resolution:**

    * Project-level permissions are additive to workspace permissions
    * Workspace role doesn't auto-grant project access
    * Explicit project access required even with workspace admin role

    **Example:**

    ```
    User is workspace_admin:
    - Has admin rights at workspace level
    - Still needs project role to access specific projects
    - Project owner can still restrict workspace admin
    ```
  </Accordion>

  <Accordion title="Group vs Individual Permissions" icon="user-group">
    **Scenario:** User has both group-based and individual permissions

    **Resolution:**

    * Combine all permissions from all sources
    * More permissive permission wins
    * Individual cannot override to be more restrictive

    **Example:**

    ```
    Group A grants: project_viewer
    Individual grant: project_editor

    Result: User has project_editor (more permissive)
    ```
  </Accordion>
</AccordionGroup>

### Permission caching and propagation

<Card title="Caching Behavior" icon="database">
  **Cache Locations:**

  * User session cache (browser)
  * Backend permission cache (per user)
  * Database role definitions (persistent)

  **Cache Invalidation:**

  * User logout clears session cache
  * Role changes propagate within 5 minutes
  * Group membership changes immediate
  * Manual cache clear via re-login

  **Troubleshooting Cache Issues:**

  1. User logs out completely
  2. Clear browser cache and cookies
  3. User logs back in
  4. Permissions refresh from database
  5. If still not working, check role assignments
</Card>

## Related documentation

<CardGroup>
  <Card title="Workspaces Access Rights" icon="shield-check" href="/5.9/setup-guides/access-management/workspaces-access-rights">
    Overview of FlowX workspace access rights and role hierarchy
  </Card>

  <Card title="Complete Permissions Matrix" icon="table" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    Detailed permission matrices for all FlowX roles
  </Card>

  <Card title="Role Selection Guide" icon="compass" href="/5.9/setup-guides/access-management/role-selection-guide">
    Practical guidance for choosing and assigning roles
  </Card>

  <Card title="Access Management Overview" icon="key" href="/5.9/setup-guides/access-management/access-management-overview">
    Overview of FlowX access management system
  </Card>
</CardGroup>


# Role selection & management guide
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/role-selection-guide

Practical guidance for selecting and assigning the right roles in FlowX Designer

<Note>
  **Documentation Navigation:**

  * [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) - Role overview and concepts
  * [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) - Detailed permission specifications
  * [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide) - Technical implementation details
  * **Role Selection Guide** (Current) - Practical scenarios and best practices
</Note>

<Info>
  This guide helps you choose the appropriate roles for different users based on their responsibilities, expertise, and access requirements.
</Info>

## Role selection decision tree

Use this decision tree to quickly identify the appropriate role:

```mermaid theme={"system"}
graph TD
    A[Need to assign role] --> B{User manages multiple workspaces?}
    B -->|Yes| C[org_admin]
    B -->|No| D{User manages workspace resources?}
    D -->|Yes, full management| E[workspace_admin]
    D -->|No| F{What is user's primary responsibility?}
    F -->|Visual design & branding| G[theme_editor]
    F -->|Runtime deployments| H[workspace_runtime_editor]
    F -->|Process operations & migrations| N[workspace_operations_editor]
    F -->|Project configuration| I{Access level needed?}
    F -->|General workspace access| J[workspace_user]
    I -->|Full control & ownership| K[project_owner]
    I -->|Full configuration access| L[project_editor]
    I -->|View only for audit/review| M[project_viewer]
```

## Role selection by persona

### Platform administrators

<Card title="Organization Administrator" icon="user-shield">
  **Role:** `org_admin`

  **Typical Responsibilities:**

  * Managing the entire FlowX platform
  * Creating and organizing workspaces
  * Managing organization-wide users and groups
  * Overseeing system health and configurations
  * Implementing organization-wide policies

  **Example Users:**

  * Platform administrators
  * IT managers
  * System architects

  **Key Considerations:**

  * Assign sparingly - only to users needing cross-workspace access
  * Has access to ALL projects across ALL workspaces
  * Should be limited to 2-3 trusted individuals
</Card>

### Business unit managers

<Card title="Workspace Administrator" icon="user-tie">
  **Role:** `workspace_admin`

  **Typical Responsibilities:**

  * Managing workspace users and access
  * Overseeing all workspace projects
  * Managing workspace themes and branding
  * Configuring workspace-level settings
  * Handling workspace resource allocation

  **Example Users:**

  * Department heads
  * Business unit managers
  * Team leads with administrative duties

  **Key Considerations:**

  * Has admin access to all projects in their workspace
  * Cannot access other workspaces without explicit assignment
  * Should be assigned to responsible leaders only
</Card>

### Developers and configurators

<CardGroup>
  <Card title="Project Owner" icon="crown">
    **Role:** `project_owner`

    **Assignment:** Automatic (assigned to project creator)

    **Typical Responsibilities:**

    * Complete project governance
    * Managing project team access
    * Final approval on project changes
    * Project lifecycle management

    **Example Users:**

    * Project leads
    * Technical architects
    * Product owners

    **Key Considerations:**

    * Automatically assigned at project creation
    * Can transfer ownership to another user
    * Only one owner per project
  </Card>

  <Card title="Project Editor" icon="code">
    **Role:** `project_editor`

    **Typical Responsibilities:**

    * Building and configuring processes
    * Designing workflows
    * Creating UI configurations
    * Managing integrations
    * Creating builds and deployments

    **Example Users:**

    * Senior developers
    * Business analysts
    * Technical configurators

    **Key Considerations:**

    * Full configuration access without ownership
    * Cannot grant/revoke project access
    * Standard role for project team members

    **Runtime Policy Access:**

    * Configurators who need to change active policy should be assigned `workspace_runtime_editor` role in their workspace
    * Even if they only have `project_viewer` access on specific projects, the workspace-level runtime role allows policy changes
  </Card>
</CardGroup>

### Specialized roles

<CardGroup>
  <Card title="UI/UX Designer" icon="palette">
    **Role:** `theme_editor`

    **Typical Responsibilities:**

    * Designing application themes
    * Managing brand assets
    * Creating and organizing fonts
    * Managing media library
    * Ensuring visual consistency

    **Example Users:**

    * UI/UX designers
    * Brand managers
    * Visual designers
    * Marketing team members

    **Key Considerations:**

    * Extends workspace\_user with design permissions
    * Can create projects but focused on visual aspects
    * Read-only for projects without explicit access
  </Card>

  <Card title="DevOps Engineer" icon="server">
    **Role:** `workspace_runtime_editor`

    **Typical Responsibilities:**

    * Creating and managing builds
    * Configuring runtime environments
    * Managing deployment policies
    * Overriding configuration parameters
    * Monitoring process instances

    **Example Users:**

    * DevOps engineers
    * Release managers
    * Technical operations staff
    * System administrators

    **Key Considerations:**

    * Extends workspace\_user with runtime permissions
    * Can manage deployments across workspace
    * Does not grant automatic project configuration access
  </Card>
</CardGroup>

<Card title="Operations Engineer" icon="rotate">
  **Role:** `workspace_operations_editor`

  **Typical Responsibilities:**

  * Managing process instance operations (migration & move token)
  * Editing process variables on active instances
  * Managing operational tasks across the workspace
  * Supporting process migrations and token movements

  **Example Users:**

  * Support engineers
  * Operations team members
  * Technical support staff
  * Process operations managers

  **Key Considerations:**

  * Extends workspace\_user with operations permissions
  * Can manage operations across workspace
  * Does not include broader runtime capabilities (builds, policies)
</Card>

### Stakeholders and reviewers

<CardGroup>
  <Card title="General Workspace User" icon="user">
    **Role:** `workspace_user`

    **Typical Responsibilities:**

    * Creating new projects
    * Working on assigned projects
    * Viewing workspace resources
    * Basic workspace participation

    **Example Users:**

    * Junior developers
    * Business analysts
    * Process designers
    * General team members

    **Key Considerations:**

    * Default role for most workspace members
    * Can create projects (becomes owner automatically)
    * Needs explicit project access to work on others' projects
  </Card>

  <Card title="Viewer / Auditor" icon="eye">
    **Role:** `project_viewer`

    **Typical Responsibilities:**

    * Reviewing project configurations
    * Auditing processes and workflows
    * Compliance checking
    * Documentation and training

    **Example Users:**

    * Business stakeholders
    * Quality assurance personnel
    * Compliance officers
    * External consultants
    * New team members (onboarding)

    **Key Considerations:**

    * Completely read-only access
    * Can test processes through interface
    * Safe for sensitive stakeholders
  </Card>
</CardGroup>

## Common role assignment scenarios

### Scenario 1: New employee onboarding

<Steps>
  <Step title="Day 1: View-only access">
    Assign `workspace_user` role at workspace level

    Grant `project_viewer` role for relevant projects

    **Rationale:** Allow new employee to explore and learn without risk
  </Step>

  <Step title="Week 2-4: Limited editing">
    Grant `project_editor` role for specific training projects

    Keep viewer access for production projects

    **Rationale:** Hands-on learning in safe environment
  </Step>

  <Step title="After onboarding: Full access">
    Grant `project_editor` role for assigned projects

    Remove training project access

    **Rationale:** Ready for production work with appropriate permissions
  </Step>
</Steps>

### Scenario 2: External consultant engagement

<AccordionGroup>
  <Accordion title="Short-term review (1-2 weeks)" icon="magnifying-glass">
    **Recommended Role:** `project_viewer`

    **Access Pattern:**

    * Grant access only to specific projects under review
    * No workspace-level role assignment
    * Time-bound access (remove after engagement)

    **Benefits:**

    * Complete visibility for review purposes
    * No risk of accidental modifications
    * Easy to audit consultant's activities
  </Accordion>

  <Accordion title="Implementation project (3-6 months)" icon="hammer">
    **Recommended Roles:**

    * Workspace level: `workspace_user`
    * Project level: `project_editor` for specific projects

    **Access Pattern:**

    * Create dedicated workspace for consultant projects
    * Grant editor access only to contracted projects
    * Regular access reviews during engagement

    **Benefits:**

    * Consultant can work independently
    * Clear boundaries on accessible projects
    * Easy cleanup after engagement ends
  </Accordion>

  <Accordion title="Long-term partnership (6+ months)" icon="handshake">
    **Recommended Roles:**

    * Workspace level: `workspace_user` or specialized role
    * Project level: `project_editor` or `project_owner` as needed

    **Access Pattern:**

    * Treat similar to internal team member
    * Consider dedicated workspace for partner projects
    * Quarterly access reviews and adjustments

    **Benefits:**

    * Full integration with team workflows
    * Appropriate access for extended engagement
    * Maintains security through regular reviews
  </Accordion>
</AccordionGroup>

### Scenario 3: Cross-functional team project

<Tabs>
  <Tab title="Small Project (2-5 people)">
    **Team Composition:**

    * 1 Project Owner (automatically assigned to creator)
    * 2-3 Project Editors (developers/analysts)
    * 1 Project Viewer (stakeholder)

    **Access Setup:**

    ```
    1. Creator starts project → becomes project_owner
    2. Grant project_editor to development team
    3. Grant project_viewer to business stakeholder
    4. Use "Everyone in workspace" group if all team members need access
    ```

    **Best Practices:**

    * Keep team small and roles simple
    * Regular sync meetings reduce need for complex permissions
    * Document decisions in project comments
  </Tab>

  <Tab title="Medium Project (5-15 people)">
    **Team Composition:**

    * 1 Project Owner (technical lead)
    * 5-8 Project Editors (developers, analysts, designers)
    * 1 Theme Editor (UI/UX specialist)
    * 2-3 Project Viewers (stakeholders, QA)
    * 1 Runtime Editor (DevOps)

    **Access Setup:**

    ```
    1. Create workspace groups:
       - "ProjectName_Developers" → project_editor
       - "ProjectName_Stakeholders" → project_viewer
    2. Assign specialized workspace roles as needed
    3. Use groups for bulk permission management
    ```

    **Best Practices:**

    * Use groups instead of individual assignments
    * Regular access reviews (monthly)
    * Document group purposes clearly
  </Tab>

  <Tab title="Large Project (15+ people)">
    **Team Composition:**

    * 1 Project Owner (product owner/architect)
    * 10-15 Project Editors (multiple teams)
    * 2-3 Theme Editors (design team)
    * 1-2 Runtime Editors (DevOps team)
    * 5-8 Project Viewers (stakeholders, compliance, QA)

    **Access Setup:**

    ```
    1. Create hierarchical groups:
       - "ProjectName_Core_Team" → project_editor
       - "ProjectName_Design_Team" → theme_editor + project_editor
       - "ProjectName_DevOps_Team" → runtime_editor + project_editor
       - "ProjectName_Stakeholders" → project_viewer
    2. Use workspace admin to manage groups centrally
    3. Implement approval workflow for access requests
    ```

    **Best Practices:**

    * Dedicated workspace admin for project
    * Automated access reviews (bi-weekly)
    * Clear escalation path for access issues
    * Document architecture decisions and ownership
  </Tab>
</Tabs>

### Scenario 4: Multi-workspace organization

<Card title="Enterprise Organization Structure" icon="building">
  **Organizational Setup:**

  **Organization Level:**

  * 2-3 `org_admin` (Platform administrators)

  **Workspace Level (per business unit):**

  * 1 `workspace_admin` (Business unit manager)
  * 15-30 `workspace_user` (Standard members)
  * 2-3 `theme_editor` (Design team)
  * 1-2 `workspace_runtime_editor` (DevOps team)
  * 1-2 `workspace_operations_editor` (Operations/Support team)

  **Project Level (varies by project):**

  * Projects follow patterns from Scenario 3

  **Access Patterns:**

  * Each business unit has dedicated workspace
  * Cross-workspace collaboration via library sharing
  * Central DevOps team has runtime\_editor in all workspaces
  * Central design team has theme\_editor in relevant workspaces
  * Central operations team has operations\_editor for process management

  **Governance:**

  * Monthly access reviews by workspace\_admin
  * Quarterly organization-wide audit by org\_admin
  * Automated alerts for inactive users
  * Clear documentation of cross-workspace access
</Card>

## Role escalation matrix

When should you upgrade a user's role?

| Current Role      | Escalate To         | Trigger Conditions                                                         | Approval Required                |
| ----------------- | ------------------- | -------------------------------------------------------------------------- | -------------------------------- |
| `project_viewer`  | `project_editor`    | User needs to make configuration changes<br />Completed onboarding period  | Project Owner                    |
| `workspace_user`  | `theme_editor`      | User assigned to design responsibilities<br />Demonstrated design skills   | Workspace Admin                  |
| `workspace_user`  | `runtime_editor`    | User assigned to DevOps responsibilities<br />Deployment management needed | Workspace Admin                  |
| `workspace_user`  | `operations_editor` | User assigned to operations responsibilities<br />Process migration needs  | Workspace Admin                  |
| `project_editor`  | `project_owner`     | Original owner leaving<br />User taking over project leadership            | Current Owner or Workspace Admin |
| `workspace_user`  | `workspace_admin`   | User promoted to management<br />Administrative duties assigned            | Organization Admin               |
| `workspace_admin` | `org_admin`         | User taking platform-wide responsibilities<br />Multi-workspace management | Existing Org Admin + Management  |

<Warning>
  Always follow the principle of least privilege. Escalate roles only when necessary and document the business justification.
</Warning>

## Role de-escalation and removal

### When to downgrade roles

<AccordionGroup>
  <Accordion title="Project Completion" icon="check-circle">
    **Scenario:** Project is completed and moved to maintenance

    **Action:**

    * Downgrade most `project_editor` to `project_viewer`
    * Keep 1-2 editors for maintenance
    * Keep project\_owner for governance

    **Timing:** At project completion milestone
  </Accordion>

  <Accordion title="Role Change" icon="user-pen">
    **Scenario:** User moves to different team or responsibilities

    **Action:**

    * Remove access to old projects
    * Assign appropriate role for new responsibilities
    * Transfer project\_owner if applicable

    **Timing:** During role transition period
  </Accordion>

  <Accordion title="Contractor End" icon="user-xmark">
    **Scenario:** Contractor engagement ends

    **Action:**

    * Remove all workspace access
    * Document contractor's contributions
    * Archive or transfer project ownership if needed

    **Timing:** On contractor's last day
  </Accordion>

  <Accordion title="Security Incident" icon="triangle-exclamation">
    **Scenario:** Suspicious activity or policy violation

    **Action:**

    * Immediate suspension of access
    * Investigation by security/admin team
    * Appropriate remediation based on findings

    **Timing:** Immediately upon detection
  </Accordion>
</AccordionGroup>

### Access removal checklist

<Steps>
  <Step title="Identify all access points">
    * List all workspaces user has access to
    * Identify all projects with direct access
    * Check group memberships
    * Review project ownership assignments
  </Step>

  <Step title="Transfer ownership">
    * Transfer project\_owner role if user owns projects
    * Update project documentation with new owner
    * Notify project stakeholders of change
  </Step>

  <Step title="Remove access">
    * Remove from workspace-level roles
    * Remove from project-level access
    * Remove from all groups
    * Verify removal in system
  </Step>

  <Step title="Document and communicate">
    * Document reason for removal
    * Update team rosters and directories
    * Communicate changes to affected teams
    * Archive for compliance if needed
  </Step>
</Steps>

## Role assignment anti-patterns

<Warning>
  Avoid these common mistakes when assigning roles:
</Warning>

### Anti-pattern 1: Everyone is an admin

**Problem:**

* Assigning `workspace_admin` or `org_admin` to too many users
* "Just in case" administrative access

**Impact:**

* Reduced security and accountability
* Increased risk of accidental changes
* Difficult to audit who made changes

**Solution:**

* Limit admin roles to actual administrators
* Use `project_editor` or `project_owner` for project-level needs
* Implement proper access request workflow

### Anti-pattern 2: Never updating roles

**Problem:**

* Roles assigned during onboarding never reviewed
* Users retain access after role changes
* Inactive users still have full access

**Impact:**

* Security vulnerabilities accumulate
* Compliance issues with access audits
* Potential data breaches

**Solution:**

* Quarterly access reviews
* Automated inactive user detection
* Role-based access recertification

### Anti-pattern 3: Individual assignments instead of groups

**Problem:**

* Assigning roles to individual users instead of groups
* Not using the "Everyone in workspace" group
* Managing access one user at a time

**Impact:**

* High administrative overhead
* Inconsistent access patterns
* Difficult to scale

**Solution:**

* Create groups for teams and functions
* Use groups for project access
* Individual assignments only for exceptions

### Anti-pattern 4: Too granular or too broad

**Problem:**

* Creating overly complex permission structures
* OR giving everyone the same high-level access

**Impact:**

* Confusion about who can do what
* Either too restrictive or too permissive
* Difficult to maintain

**Solution:**

* Start with predefined roles
* Use workspace/project boundaries naturally
* Add granularity only when truly needed

### Anti-pattern 5: No documentation

**Problem:**

* Access decisions not documented
* No record of why users have certain roles
* No clear ownership of access management

**Impact:**

* Cannot audit access decisions
* Difficult to troubleshoot access issues
* Compliance problems

**Solution:**

* Document all non-standard role assignments
* Maintain role assignment justifications
* Clear ownership of access management process

## Groups and access management

<Info>
  FlowX uses groups to simplify access management across users. Understanding built-in groups and creating custom groups efficiently manages permissions at scale.
</Info>

### Built-in workspace groups

#### Everyone in workspace group

Every workspace automatically includes a special system-managed group for all workspace members:

<Card title="all_users_[workspace_name]" icon="users">
  **Display Name in UI:** `Everyone from <workspace name>`

  **Purpose:**
  Provides convenient access management for all users associated with a workspace.

  **Automatic Behavior:**

  * Created automatically during workspace provisioning
  * Cannot be edited, deleted, or duplicated
  * Users automatically added when granted workspace access (direct or through another group)
  * Users automatically removed when workspace access is revoked
  * Pre-selected by default when creating new projects/libraries
  * Appears in user/group search results when granting project access

  **Common Use Cases:**

  * Grant all workspace members read access to reference projects
  * Provide baseline visibility across all workspace projects
  * Simplify onboarding by giving new users automatic access to shared resources
  * Create workspace-wide announcements or shared libraries

  **Example:**

  ```
  Workspace: "Product Development"
  Auto-created group: "all_users_product_development"
  Display name: "Everyone from Product Development"
  ```

  When creating a new project in "Product Development" workspace, the group "Everyone from Product Development" appears pre-selected, allowing immediate assignment of a role (viewer, editor, etc.) to all workspace members.
</Card>

<Warning>
  **Cannot Exclude Individual Members**

  The "Everyone in workspace" group includes ALL workspace members without exception. You cannot:

  * Remove specific users from this group
  * Create exceptions or exclusions
  * Modify group membership manually

  If you need selective access, create custom groups for specific teams or roles.
</Warning>

### Custom groups

<Tabs>
  <Tab title="Creating Groups">
    #### When to create custom groups

    Create custom groups when you need:

    * Team-based access (e.g., "Development Team", "QA Team")
    * Role-based access (e.g., "Senior Developers", "Stakeholders")
    * Project-specific access (e.g., "Project Alpha Team")
    * Cross-functional teams (e.g., "Release Management", "Architecture Board")

    #### Group creation best practices

    <Steps>
      <Step title="Plan group structure">
        Identify natural team boundaries and access patterns before creating groups.

        **Good Examples:**

        * `dev_team_frontend`
        * `stakeholders_finance_dept`
        * `project_phoenix_core_team`

        **Poor Examples:**

        * `random_users`
        * `temp_group_1`
        * `johns_team` (too specific, not transferable)
      </Step>

      <Step title="Use descriptive names">
        Group names should clearly indicate purpose and membership.

        **Naming Convention:**
        `[function]_[department/project]_[sub-group]`

        **Examples:**

        * `developers_mobile_ios`
        * `viewers_executive_leadership`
        * `editors_project_migration`
      </Step>

      <Step title="Document group purpose">
        Add clear descriptions explaining:

        * Who should be members
        * What access the group provides
        * When to use the group for access grants
      </Step>

      <Step title="Assign appropriate permissions">
        Grant groups workspace-level roles, then use groups when assigning project access:

        ```
        1. Create group: "Mobile Development Team"
        2. Add members: All mobile developers
        3. Grant workspace role: workspace_user
        4. Use group for project access: Grant project_editor to "Mobile Development Team" on mobile projects
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Managing Groups">
    #### Group lifecycle management

    **Adding Members:**

    * Add users individually
    * Bulk import from CSV
    * Integrate with identity provider groups (if configured)

    **Removing Members:**

    * Individual removal
    * Automatic removal when user leaves workspace
    * Bulk update operations

    **Modifying Groups:**

    * Update group name and description
    * Change group membership
    * Review and audit group access

    <Warning>
      **Deleting Groups Impact**

      Deleting a group:

      * Removes all access granted through that group
      * Does NOT delete the users themselves
      * Cannot be undone
      * May leave users without expected access

      Always verify group usage before deletion:

      1. Check which projects use the group
      2. Identify affected users
      3. Plan alternative access methods
      4. Communicate changes to affected users
    </Warning>
  </Tab>

  <Tab title="Group Strategies">
    #### Access patterns using groups

    **Pattern 1: Hierarchical Teams**

    ```
    all_users_product_development (workspace)
    ├── team_backend_developers
    ├── team_frontend_developers
    ├── team_qa_engineers
    └── team_product_owners
    ```

    Each sub-group receives different project roles based on responsibilities.

    **Pattern 2: Project-Based Groups**

    ```
    project_alpha_core_team → project_editor
    project_alpha_stakeholders → project_viewer
    project_alpha_devops → project_editor + workspace_runtime_editor
    project_alpha_operations → project_viewer + workspace_operations_editor
    ```

    Groups organized around specific projects for clear access boundaries.

    **Pattern 3: Cross-Functional Groups**

    ```
    architecture_review_board → project_viewer on all projects
    release_management_team → workspace_runtime_editor
    security_team → project_viewer + audit access
    ```

    Groups that span multiple projects with specialized access needs.

    **Pattern 4: External Collaboration**

    ```
    external_consultants_acme → project_editor on assigned projects only
    external_auditors_bigfour → project_viewer on compliance projects
    partners_vendor_xyz → project_viewer on integration projects
    ```

    Separate groups for external parties with time-bound access.
  </Tab>
</Tabs>

### Group vs. individual assignment decision matrix

| Scenario                                 | Use Group | Use Individual Assignment |
| ---------------------------------------- | --------- | ------------------------- |
| 5+ users need same access                | ✅ Yes     | ❌ No                      |
| Access pattern is temporary (\< 1 month) | ❌ No      | ✅ Yes                     |
| Access follows team structure            | ✅ Yes     | ❌ No                      |
| One-off exception for specific user      | ❌ No      | ✅ Yes                     |
| Access will change frequently            | ❌ No      | ✅ Yes                     |
| Multiple projects need same team access  | ✅ Yes     | ❌ No                      |
| Executive/stakeholder with unique access | ❌ No      | ✅ Yes                     |
| New team being formed                    | ✅ Yes     | ❌ No                      |

## Troubleshooting permission issues

<Info>
  Common permission-related issues and their solutions. Use this guide to quickly diagnose and resolve access problems.
</Info>

### Common error scenarios

<AccordionGroup>
  <Accordion title="Error: &#x22;Cannot see Projects menu&#x22;" icon="eye-slash">
    **Symptoms:**

    * Projects menu entry not visible
    * Workspace appears empty
    * Cannot navigate to any projects

    **Possible Causes:**

    1. No workspace access granted
    2. Missing `workspace_read` permission
    3. Not a member of any workspace

    **Solutions:**

    <Steps>
      <Step title="Verify workspace membership">
        Check if user has been granted access to the workspace:

        * Contact workspace administrator
        * Verify user appears in workspace Users list
        * Check group membership if access is group-based
      </Step>

      <Step title="Confirm workspace role">
        User needs at minimum `workspace_user` role:

        * Review user's assigned roles in workspace
        * Verify `workspace_read` permission is included
        * If missing, workspace admin should assign appropriate role
      </Step>

      <Step title="Clear cache and re-login">
        Sometimes permissions don't update immediately:

        * Log out of FlowX Designer
        * Clear browser cache
        * Log back in
        * Check if Projects menu now appears
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Error: &#x22;Can see project but cannot edit&#x22;" icon="lock">
    **Symptoms:**

    * Project appears in list
    * Can open project but all controls disabled
    * Configure shows as "View" instead
    * No Save buttons visible

    **Possible Causes:**

    1. Have `project_viewer` role instead of `project_editor`
    2. Have read-only permissions on project
    3. Project is locked or archived

    **Solutions:**

    <Steps>
      <Step title="Check project role">
        Verify assigned project role:

        * Open project
        * Look for edit controls (should be hidden if viewer)
        * Check contextual menu (Configure vs View)
      </Step>

      <Step title="Request role upgrade">
        Contact project owner to grant edit access:

        * Identify project owner (automatic creator or transferred owner)
        * Request `project_editor` role
        * Provide business justification for edit access
      </Step>

      <Step title="Verify project status">
        Ensure project is active:

        * Check if project is archived
        * Verify project version is editable
        * Confirm no system locks in place
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Error: &#x22;Cannot create builds&#x22;" icon="ban">
    **Symptoms:**

    * No "Create build" button visible
    * Import build action missing
    * Runtime menu entries not accessible

    **Possible Causes:**

    1. Missing `wks_builds_create` permission
    2. Don't have `workspace_runtime_editor` role
    3. Workspace-level runtime access not granted

    **Solutions:**

    <Steps>
      <Step title="Request runtime access">
        Contact workspace administrator:

        * Explain need for build creation
        * Request `workspace_runtime_editor` role
        * Alternative: Request specific `wks_builds_create` permission
      </Step>

      <Step title="Understand scope change">
        Note that runtime permissions moved to workspace level in v5.0:

        * Old: Per-project runtime access
        * New: Workspace-wide runtime access
        * May need different permission strategy
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Error: &#x22;User added to group but still no access&#x22;" icon="users-slash">
    **Symptoms:**

    * User appears in group membership list
    * User still cannot access expected resources
    * Group-based permissions not applying

    **Possible Causes:**

    1. Group not assigned to project
    2. Group has insufficient permissions
    3. Permission cache not refreshed
    4. Individual permission overrides group

    **Solutions:**

    <Steps>
      <Step title="Verify group assignments">
        Check where group is used:

        * Check project-level access for group
        * Verify group has appropriate roles assigned
      </Step>

      <Step title="Check permission hierarchy">
        Understand permission precedence:

        * Individual permissions may override group
        * Multiple groups combine permissions
        * A user's permissions in the context of a project is the reunion of their permissions given though groups or individual assignments
      </Step>

      <Step title="Force refresh">
        Clear permission cache:

        * User logs out completely
        * Clear browser cache and cookies
        * User logs back in
        * Permissions should refresh from backend
      </Step>

      <Step title="Review group role">
        Ensure group has correct role:

        * Check group's workspace-level role
        * Verify group's project-level role
        * Confirm role includes needed permissions
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Error: &#x22;Project owner left, cannot manage access&#x22;" icon="user-xmark">
    **Symptoms:**

    * Original project owner no longer with organization
    * Cannot grant/revoke project access
    * Project governance blocked

    **Possible Causes:**

    1. Project ownership not transferred
    2. No other users have admin rights on project
    3. Workspace admin access not configured

    **Solutions:**

    <Steps>
      <Step title="Contact workspace administrator">
        Workspace admin can help:

        * Has `projects_admin` permission
        * Can grant access to projects
        * Can help identify new owner
      </Step>

      <Step title="Transfer project ownership">
        Workspace admin or org admin can:

        * Assign new project owner
        * Transfer governance rights
        * Update project documentation
      </Step>

      <Step title="Prevent future issues">
        Implement ownership best practices:

        * Always have 2+ users with project\_editor minimum
        * Document ownership succession plan
        * Review project ownership quarterly
        * Assign workspace admin as backup owner for critical projects
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Best practices summary

<CardGroup>
  <Card title="Start Conservative" icon="shield-check">
    Begin with `project_viewer` or `workspace_user` and escalate as needed based on demonstrated needs
  </Card>

  <Card title="Use Groups" icon="users">
    Create and use groups for teams and functions rather than managing individual user access
  </Card>

  <Card title="Regular Reviews" icon="calendar-check">
    Quarterly access reviews, remove inactive users, validate permissions match responsibilities
  </Card>

  <Card title="Document Decisions" icon="file-text">
    Maintain records of role assignments, especially for elevated privileges and exceptions
  </Card>

  <Card title="Use Automation" icon="robot">
    Use group memberships and role inheritance to reduce manual access management
  </Card>

  <Card title="Plan for Transitions" icon="arrows-rotate">
    Have clear processes for role changes, project ownership transfers, and access removal
  </Card>
</CardGroup>

## Keycloak roles vs Designer roles

FlowX uses two separate role systems. Understanding the difference prevents common confusion:

| Aspect          | Keycloak realm roles                           | FlowX Designer roles                             |
| --------------- | ---------------------------------------------- | ------------------------------------------------ |
| **Managed in**  | Keycloak Admin Console                         | FlowX Designer (Workspaces)                      |
| **Purpose**     | Service authentication, runtime process access | Designer UI access, project permissions          |
| **Assigned to** | Users and service accounts                     | Users and groups within workspaces               |
| **Examples**    | `SA_FLOWX`, `default-roles-flowx`              | `org_admin`, `workspace_admin`, `project_editor` |

### Keycloak realm roles quick reference

| Role                  | Purpose                                                                                   | Who needs it                           |
| --------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- |
| `SA_FLOWX`            | Service account role. Identifies FlowX platform services for inter-service communication. | Service accounts only, not human users |
| `default-roles-flowx` | Default realm role automatically assigned to new users in the FlowX Keycloak realm.       | All users (assigned automatically)     |

<Info>
  In FlowX 4.x, roles like `FLOWX_ADMIN`, `FLOWX_CONFIGURATOR`, and `FLOWX_VIEWER` were Keycloak realm roles that controlled Designer access. In FlowX 5.0+, these have been replaced by the Designer role system (workspace\_admin, project\_editor, etc.). See the [legacy role migration](/5.9/setup-guides/access-management/workspaces-access-rights#legacy-role-migration) for the full conversion table.
</Info>

<Warning>
  Do not confuse Keycloak realm roles with FlowX Designer roles. Assigning a user `workspace_admin` in Keycloak has no effect — it must be assigned through the FlowX Designer interface. Keycloak only handles authentication (login), while Designer handles authorization (what you can access).
</Warning>

***

## Related documentation

<CardGroup>
  <Card title="Workspaces Access Rights" icon="shield-check" href="/5.9/setup-guides/access-management/workspaces-access-rights">
    Overview of FlowX workspace access rights and role hierarchy
  </Card>

  <Card title="Complete Permissions Matrix" icon="table" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    Detailed permission matrices for all FlowX roles
  </Card>

  <Card title="Permission Reference Guide" icon="book" href="/5.9/setup-guides/access-management/permission-reference-guide">
    Technical implementation details, UI mappings, and naming conventions
  </Card>

  <Card title="Access Management Overview" icon="key" href="/5.9/setup-guides/access-management/access-management-overview">
    Overview of FlowX access management system
  </Card>

  <Card title="Configuring IAM Solution" icon="lock" href="/5.9/setup-guides/access-management/configuring-an-iam-solution">
    Setting up identity and access management
  </Card>

  <Card title="Workspaces" icon="briefcase" href="/5.9/docs/projects/workspaces">
    Understanding workspaces and organizing projects
  </Card>
</CardGroup>


# Complete roles & permissions matrix
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/roles-permissions-matrix

Detailed permission matrices for all FlowX roles across organization, workspace, and project levels

<Note>
  **Documentation Navigation:**

  * [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) - Role overview and concepts
  * **Complete Permissions Matrix** (Current) - Detailed permission specifications
  * [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide) - Technical implementation details
  * [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide) - Practical scenarios and best practices
</Note>

<Info>
  This page provides comprehensive permission matrices for all predefined roles in FlowX. Use this as a reference when planning access control strategies.
</Info>

## How to use this reference

<Steps>
  <Step title="Identify the role level">
    Determine whether you need organization, workspace, or project-level access
  </Step>

  <Step title="Find the appropriate role">
    Review the role descriptions and select the one matching your requirements
  </Step>

  <Step title="Verify permissions">
    Check the detailed permission matrix to ensure it meets your needs
  </Step>

  <Step title="Implement access control">
    Assign roles according to the principle of least privilege
  </Step>
</Steps>

## Permission legend

The permission matrices use the following symbols:

| Symbol | Meaning                                      |
| ------ | -------------------------------------------- |
| ✅      | Permission is assigned                       |
| ❌      | Permission is not assigned                   |
| ⬜      | Permission is not available for this context |

## Organization level permissions

### Organization admin permission matrix

The `org_admin` role has the following permissions:

<Tabs>
  <Tab title="Organization Administration">
    | Resource     | Read | Edit | Create | Delete | Admin | Comments                             |
    | ------------ | ---- | ---- | ------ | ------ | ----- | ------------------------------------ |
    | Organization | ⬜    | ✅    | ⬜      | ⬜      | ⬜     | Organization settings management     |
    | Workspaces   | ✅    | ✅    | ✅      | ✅      | ✅     | Complete workspace lifecycle control |
    | Users        | ✅    | ✅    | ✅      | ✅      | ⬜     | Organization user management         |
    | Groups       | ✅    | ✅    | ✅      | ✅      | ⬜     | User group management                |
  </Tab>

  <Tab title="System Management">
    | Resource      | Read | Edit | Create | Delete | Comments                                                                                                                                                                         |
    | ------------- | ---- | ---- | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Out of office | ✅    | ✅    | ✅      | ✅      | Out of office policy management                                                                                                                                                  |
    | Fonts         | ✅    | ✅    | ✅      | ✅      | Global font resource management                                                                                                                                                  |
    | AI providers  | ✅    | ✅    | ⬜      | ⬜      | Gated by `org_ai_providers_read` / `org_ai_providers_edit`. Controls the AI Settings nav entry, Model Providers, and Defaults & Fallbacks pages in the organization admin space. |
  </Tab>

  <Tab title="Monitoring & Audit">
    | Resource        | Read | Edit | Create | Delete | Comments                                                                                                                                                       |
    | --------------- | ---- | ---- | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Audit logs      | ✅    | ❌    | ❌      | ❌      | Read-only access to system audit                                                                                                                               |
    | Platform status | ✅    | ❌    | ❌      | ❌      | System health monitoring                                                                                                                                       |
    | Org Env Info    | ⚠️   | ⚠️   | ❌      | ❌      | *Deprecated in 5.7.0.* Manual Configure Environment Info form removed; permission retained for backward compatibility but no longer surfaces a UI entry point. |
    | Org Audit log   | ✅    | ❌    | ❌      | ❌      | Organization-specific audit access                                                                                                                             |
  </Tab>
</Tabs>

<Card title="Organization Admin Role Constraints" icon="lock">
  **Management Rules:**

  * Cannot be edited, duplicated, or deleted
  * Can only be assigned in the Organization admin space
  * Hidden from workspace role lists
  * Cannot be assigned at workspace level
  * Must be assigned to at least one user during initial setup
</Card>

## Workspace level permissions

### Workspace admin permission matrix

The `workspace_admin` role has the following permissions:

<Tabs>
  <Tab title="Workspace Entities">
    | Resource             | Read | Edit | Create | Admin | Delete | Comments                                                                                                                                      |
    | -------------------- | ---- | ---- | ------ | ----- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
    | Projects & libraries | ⬜    | ⬜    | ✅      | ✅     | ⬜      | Can create projects and has admin rights on projects/libraries in the workspace (even without being given explicit access)                    |
    | Fonts                | ✅    | ✅    | ✅      | ⬜     | ✅      | Can see all Fonts available for the workspace but is not allowed to edit or add new ones                                                      |
    | Global media library | ✅    | ✅    | ✅      | ⬜     | ✅      | Can add new Global media files as well as edit/delete all Global media files available for the workspace                                      |
    | Themes               | ✅    | ✅    | ✅      | ⬜     | ✅      | Can add new themes as well as edit/delete all themes available for the workspace                                                              |
    | Workspace audit logs | ✅    | ⬜    | ⬜      | ⬜     | ⬜      | Can see and filter all audit logs for that workspace                                                                                          |
    | AI models            | ✅    | ✅    | ⬜      | ⬜     | ⬜      | Gated by `wks_ai_models_read` / `wks_ai_models_edit`. Controls workspace-level AI model assignments (defaults, fallbacks) per workspace type. |
  </Tab>

  <Tab title="Runtime Entities">
    | Resource                           | Read | Edit | Create | Delete | Comments                                                                                                                                    |
    | ---------------------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
    | Workspace builds                   | ✅    | ⬜    | ✅      | ⬜      | Can create a build for any project/library, as well as see and run all builds within the workspace                                          |
    | Workspace active policy            | ✅    | ✅    | ⬜      | ⬜      | Can add a new active policy override as well as see and edit the active policy and its overrides on all projects/libraries in the workspace |
    | Scheduled processes                | ✅    | ✅    | ⬜      | ✅      | Can see all scheduled processes on all projects/libraries in the workspace as well as enable/disable them                                   |
    | Configuration parameters overrides | ✅    | ✅    | ✅      | ✅      | Can add new configuration parameters overrides as well as see all overrides on all projects/libraries in the workspace                      |
    | Process instances                  | ✅    | ✅    | ⬜      | ⬜      | Can see and filter all process instances on all projects/libraries in the workspace                                                         |
    | Tasks                              | ✅    | ⬜    | ⬜      | ⬜      | Can see and filter all tasks available for them on all projects/libraries in the workspace                                                  |
    | Operations                         | ✅    | ✅    | ✅      | ✅      | Can create, view, edit, and delete all operations within the workspace (migration & move token)                                             |
    | Process variables                  | ⬜    | ✅    | ⬜      | ⬜      | Can edit process variables on all projects/libraries in the workspace                                                                       |
  </Tab>

  <Tab title="Access Management">
    | Resource                          | Read | Edit | Create | Delete | Comments                                                                                                                |
    | --------------------------------- | ---- | ---- | ------ | ------ | ----------------------------------------------------------------------------------------------------------------------- |
    | Workspace management              | ✅    | ✅    | ⬜      | ⬜      | Permission added so that the user can see the resources he creates or is assigned to                                    |
    | Users                             | ✅    | ✅    | ✅      | ✅      | Can see and modify all users assigned to the workspace, as well as their groups and access within the current workspace |
    | Workspace groups                  | ✅    | ✅    | ✅      | ✅      | Can add new groups as well as edit/delete all groups available for the workspace                                        |
    | Workspace roles                   | ✅    | ✅    | ✅      | ✅      | Complete workspace role management                                                                                      |
    | Workspace platform status         | ✅    | ⬜    | ⬜      | ⬜      | Can see and export the Platform status details                                                                          |
    | Workspace environment information | ⚠️   | ⬜    | ⬜      | ⬜      | *Deprecated in 5.7.0.* Environment Info UI removed; permission retained for backward compatibility.                     |
  </Tab>
</Tabs>

<Card title="Workspace Admin Role Constraints" icon="settings">
  **Management Rules:**

  * Cannot be edited or deleted (predefined role)
  * Listed in workspace role management interfaces
  * Can be assigned to users/groups within the workspace
  * Can be assigned when granting access to workspace
  * Cannot manage organization-wide settings
</Card>

### Workspace user permission matrix

The `workspace_user` role has the following permissions:

<Tabs>
  <Tab title="Workspace Entities">
    | Resource             | Read | Edit | Create | Admin | Delete | Comments                                                                                                                                                                                           |
    | -------------------- | ---- | ---- | ------ | ----- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Projects & libraries | ⬜    | ⬜    | ✅      | ⬜     | ⬜      | Can create projects, can edit and see projects/libraries they are given explicit access to or where they are owners. See [Project level](#project-level-permissions) permissions for more details. |
    | Fonts                | ✅    | ⬜    | ⬜      | ⬜     | ⬜      | Can see all Fonts available for the workspace but is not allowed to edit or add new ones                                                                                                           |
    | Global media library | ✅    | ⬜    | ⬜      | ⬜     | ⬜      | Is able to view all global media files, but is not allowed to edit or add new files                                                                                                                |
    | Themes               | ✅    | ⬜    | ⬜      | ⬜     | ⬜      | Can see all Themes available for the workspace but is not allowed to edit or add new ones                                                                                                          |
    | Workspace audit logs | ✅    | ⬜    | ⬜      | ⬜     | ⬜      | Can see and filter all audit logs for that workspace                                                                                                                                               |
  </Tab>

  <Tab title="Runtime Entities">
    | Resource                           | Read | Edit | Create | Delete | Comments                                                                                                               |
    | ---------------------------------- | ---- | ---- | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------- |
    | Workspace builds                   | ✅    | ⬜    | ⬜      | ⬜      | Can see and run all builds on projects/libraries they create or they are given explicit access to                      |
    | Workspace active policy            | ✅    | ⬜    | ⬜      | ⬜      | Can see the active policy and its overrides on projects/libraries they create or they are given explicit access to     |
    | Scheduled processes                | ✅    | ⬜    | ⬜      | ⬜      | Can see all scheduled processes on projects/libraries they create or they are given explicit access to                 |
    | Configuration parameters overrides | ✅    | ⬜    | ⬜      | ⬜      | Can see all configuration parameters overrides on projects/libraries they create or they are given explicit access to  |
    | Process instances                  | ✅    | ✅    | ⬜      | ⬜      | Can see and filter all process instances on projects/libraries they create or they are given explicit access to        |
    | Tasks                              | ✅    | ⬜    | ⬜      | ⬜      | Can see and filter all tasks available for them on projects/libraries they create or they are given explicit access to |
    | Operations                         | ✅    | ⬜    | ✅      | ⬜      | Can create operations and view all operations within the workspace (migration & move token)                            |
    | Process variables                  | ⬜    | ✅    | ⬜      | ⬜      | Can edit process variables on projects/libraries they create or are given explicit access to                           |
  </Tab>

  <Tab title="Access Management">
    | Resource                          | Read | Edit | Create | Delete | Comments                                                                                                     |
    | --------------------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------ |
    | Workspace management              | ✅    | ⬜    | ⬜      | ⬜      | Permission added so that the user can see the resources he creates or is assigned to                         |
    | Users                             | ✅    | ⬜    | ⬜      | ⬜      | Can see all users assigned to the workspace, as well as their groups and access within the current workspace |
    | Workspace groups                  | ✅    | ⬜    | ⬜      | ⬜      | View workspace groups but can't manage                                                                       |
    | Workspace roles                   | ✅    | ⬜    | ⬜      | ⬜      | View workspace roles but can't manage                                                                        |
    | Workspace platform status         | ✅    | ⬜    | ⬜      | ⬜      | Can see and export the Platform status details                                                               |
    | Workspace environment information | ⚠️   | ⬜    | ⬜      | ⬜      | *Deprecated in 5.7.0.* Environment Info UI removed; permission retained for backward compatibility.          |
  </Tab>
</Tabs>

<Card title="Workspace User Role Constraints" icon="user">
  **Management Rules:**

  * Cannot be edited or deleted (predefined role)
  * Can be duplicated to create custom variations (future feature)
  * Default role for most workspace members
  * Can be assigned when granting access to workspace
  * Limited administrative capabilities
</Card>

### Theme editor permission matrix

The `theme_editor` role extends `workspace_user` with additional permissions:

<Tabs>
  <Tab title="Additional Permissions">
    | Resource             | Read | Edit | Create | Delete | Comments                                                                                                 |
    | -------------------- | ---- | ---- | ------ | ------ | -------------------------------------------------------------------------------------------------------- |
    | Fonts                | ✅    | ✅    | ✅      | ✅      | Can see all Fonts available for the workspace but is not allowed to edit or add new ones                 |
    | Global media library | ✅    | ✅    | ✅      | ✅      | Can add new Global media files as well as edit/delete all Global media files available for the workspace |
    | Themes               | ✅    | ✅    | ✅      | ✅      | Can add new themes as well as edit/delete all themes available for the workspace                         |
  </Tab>

  <Tab title="Inherited from workspace_user">
    All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.
  </Tab>
</Tabs>

<Card title="Theme Editor Role Constraints" icon="palette">
  **Management Rules:**

  * Same base constraints as `workspace_user`
  * Cannot be edited or deleted (predefined role)
  * Can be duplicated to create custom variations (future feature)
  * Specialized role for UI/UX designers and brand managers
</Card>

### Workspace runtime editor permission matrix

The `workspace_runtime_editor` role extends `workspace_user` with additional permissions:

<Tabs>
  <Tab title="Additional Runtime Permissions">
    | Resource                           | Read | Edit | Create | Delete | Comments                                                                                                                                    |
    | ---------------------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
    | Workspace builds                   | ✅    | ⬜    | ✅      | ⬜      | Can create a build for any project/library, as well as see and run all builds within the workspace                                          |
    | Workspace active policy            | ✅    | ✅    | ⬜      | ⬜      | Can add a new active policy override as well as see and edit the active policy and its overrides on all projects/libraries in the workspace |
    | Scheduled processes                | ✅    | ✅    | ⬜      | ✅      | Can see all scheduled processes on all projects/libraries in the workspace as well as enable/disable them                                   |
    | Configuration parameters overrides | ✅    | ✅    | ✅      | ✅      | Can add new configuration parameters overrides as well as see all overrides on all projects/libraries in the workspace                      |
    | Process instances                  | ✅    | ✅    | ⬜      | ⬜      | Can see and filter all process instances on all projects/libraries in the workspace                                                         |
    | Tasks                              | ✅    | ⬜    | ⬜      | ⬜      | Can see and filter all tasks available for them on all projects/libraries in the workspace                                                  |
    | Operations                         | ✅    | ✅    | ✅      | ✅      | Can create, view, edit, and delete all operations within the workspace (migration & move token)                                             |
    | Process variables                  | ⬜    | ✅    | ⬜      | ⬜      | Can edit process variables on all projects/libraries in the workspace                                                                       |
  </Tab>

  <Tab title="Inherited from workspace_user">
    All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.
  </Tab>
</Tabs>

<Card title="Runtime Editor Role Constraints" icon="gear">
  **Management Rules:**

  * Same base constraints as `workspace_user`
  * Cannot be edited or deleted (predefined role)
  * Can be duplicated to create custom variations (future feature)
  * Specialized role for DevOps and runtime environment administrators
</Card>

### Workspace operations editor permission matrix

The `workspace_operations_editor` role extends `workspace_user` with additional permissions:

<Tabs>
  <Tab title="Additional Operations Permissions">
    | Resource          | Read | Edit | Create | Delete | Comments                                                                                        |
    | ----------------- | ---- | ---- | ------ | ------ | ----------------------------------------------------------------------------------------------- |
    | Process instances | ✅    | ✅    | ⬜      | ⬜      | Can see and filter all process instances on all projects/libraries in the workspace             |
    | Operations        | ✅    | ✅    | ✅      | ✅      | Can create, view, edit, and delete all operations within the workspace (migration & move token) |
    | Process variables | ⬜    | ✅    | ⬜      | ⬜      | Can edit process variables on all projects/libraries in the workspace                           |
  </Tab>

  <Tab title="Inherited from workspace_user">
    All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.
  </Tab>
</Tabs>

<Card title="Operations Editor Role Constraints" icon="rotate">
  **Management Rules:**

  * Same base constraints as `workspace_user`
  * Cannot be edited or deleted (predefined role)
  * Can be duplicated to create custom variations (future feature)
  * Specialized role for operations management (process migration & token operations)
</Card>

## Project level permissions

### Project owner permission matrix

The `project_owner` role has the following permissions:

<Tabs>
  <Tab title="Project Administration">
    | Resource             | Read | Edit | Create | Delete | Admin/Owner | Comments                                                                       |
    | -------------------- | ---- | ---- | ------ | ------ | ----------- | ------------------------------------------------------------------------------ |
    | Projects & Libraries | ✅    | ✅    | ⬜      | ✅      | ✅           | Has admin rights on all projects/libraries in the workspace he is the owner of |
  </Tab>

  <Tab title="Configuration Resources">
    | Resource                              | Read | Edit | Create | Delete | Comments                                                                                                                                                                                                            |
    | ------------------------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Processes                             | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Project data model                    | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Enumerations                          | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Media library & Document Intelligence | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Notification templates                | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Document templates                    | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Views                                 | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Stages                                | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Allocation rules                      | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Data Sources                          | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Workflow                              | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Reusable UI                           | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | UI Flows                              | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete UI Flows within the project (5.3+)                                                                                                                                                           |
    | Reusable Business Rules               | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Dependencies                          | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | Configuration parameters              | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                                                                                                                                                             |
    | AI agents                             | ⬜    | ✅    | ⬜      | ⬜      | Gated by the `aiagent_edit` permission. Controls visibility of config-time agents (AI Assistant, Analyst, Designer, Developer), the AI floating action button, the Chat UI component, and AI actions on BPMN nodes. |
  </Tab>
</Tabs>

<Card title="Project Owner Role Constraints" icon="crown">
  **Management Rules:**

  * System-managed role, cannot be edited or deleted
  * Automatically assigned to user who creates project
  * Hidden from role selection interfaces
  * Cannot be manually assigned through UI
  * Permanent assignment for project lifecycle
  * Can be transferred to another user (ownership transfer)
</Card>

### Project editor permission matrix

The `project_editor` role has the following permissions:

<Tabs>
  <Tab title="Project Management">
    | Resource             | Read | Edit | Create | Delete | Comments                                                           |
    | -------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------ |
    | Projects & Libraries | ✅    | ✅    | ⬜      | ❌      | Can read and edit any project for which they are a project\_editor |
  </Tab>

  <Tab title="Configuration Resources">
    | Resource                              | Read | Edit | Create | Delete | Comments                                                                  |
    | ------------------------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------------- |
    | Processes                             | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Project data model                    | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Enumerations                          | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Media library & Document Intelligence | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Notification templates                | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Document templates                    | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Views                                 | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Stages                                | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Allocation rules                      | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Data Sources                          | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Workflow                              | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Reusable UI                           | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | UI Flows                              | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete UI Flows within the project (5.3+)                 |
    | Reusable Business Rules               | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Dependencies                          | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | Configuration parameters              | ✅    | ✅    | ✅      | ✅      | Can create/edit/delete all resources within the project                   |
    | AI agents                             | ⬜    | ✅    | ⬜      | ⬜      | Gated by the `aiagent_edit` permission. Same surfaces as `project_owner`. |
  </Tab>
</Tabs>

<Card title="Project Editor Role Constraints" icon="pen-to-square">
  **Management Rules:**

  * Cannot be edited or deleted (predefined role)
  * Can be duplicated to create custom variations (future feature)
  * Can be assigned to users/groups when granting project access
  * Standard role for project team members
  * No ownership rights (cannot grant/revoke project access)
</Card>

### Project viewer permission matrix

The `project_viewer` role has the following permissions:

<Tabs>
  <Tab title="Project Access">
    | Resource             | Read | Edit | Create | Delete | Comments                                            |
    | -------------------- | ---- | ---- | ------ | ------ | --------------------------------------------------- |
    | Projects & Libraries | ✅    | ⬜    | ⬜      | ❌      | Read-only access to project and library information |
  </Tab>

  <Tab title="Configuration Resources">
    | Resource                              | Read | Edit | Create | Delete | Comments                                                                                                      |
    | ------------------------------------- | ---- | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
    | Processes                             | ✅    | ❌    | ❌      | ❌      | View process definitions and workflows                                                                        |
    | Project data model                    | ✅    | ❌    | ❌      | ❌      | Read-only access to project data structure                                                                    |
    | Enumerations                          | ✅    | ❌    | ❌      | ❌      | View enumeration values and data structures                                                                   |
    | Media library & Document Intelligence | ✅    | ❌    | ❌      | ❌      | View media assets and document intelligence configurations                                                    |
    | Notification templates                | ✅    | ❌    | ❌      | ❌      | View notification template configurations                                                                     |
    | Document templates                    | ✅    | ❌    | ❌      | ❌      | View document template configurations                                                                         |
    | Views                                 | ✅    | ❌    | ❌      | ❌      | View UI configuration definitions                                                                             |
    | Stages                                | ✅    | ❌    | ❌      | ❌      | View process stage definitions                                                                                |
    | Allocation rules                      | ✅    | ❌    | ❌      | ❌      | View task and resource allocation rules                                                                       |
    | Data Sources                          | ✅    | ❌    | ❌      | ❌      | View system integrations and endpoints                                                                        |
    | Workflow                              | ✅    | ❌    | ❌      | ❌      | View workflow definitions and configurations                                                                  |
    | Reusable UI                           | ✅    | ❌    | ❌      | ❌      | Read-only UI component access with permission inheritance                                                     |
    | UI Flows                              | ✅    | ❌    | ❌      | ❌      | View UI Flows definitions (5.3+)                                                                              |
    | Reusable Business Rules               | ✅    | ❌    | ❌      | ❌      | Read-only function component access with permission inheritance                                               |
    | Dependencies                          | ✅    | ❌    | ❌      | ❌      | View project and library dependencies                                                                         |
    | Configuration parameters              | ✅    | ❌    | ❌      | ❌      | View project configuration parameters                                                                         |
    | AI agents                             | ⬜    | ❌    | ⬜      | ⬜      | `aiagent_edit` not granted. No `aiagent_read` exists, so project viewers do not see AI agent surfaces at all. |
  </Tab>
</Tabs>

<Card title="Project Viewer Role Constraints" icon="eye">
  **Management Rules:**

  * Cannot be edited or deleted (predefined role)
  * Can be duplicated to create custom variations (future feature)
  * Can be assigned to users/groups when granting project access
  * Safe role for stakeholders needing visibility
  * No modification capabilities
  * Can test processes and workflows through the interface
</Card>

## Role comparison matrix

### Quick reference: All roles compared

| Permission Category       | org\_admin | workspace\_admin | workspace\_user | theme\_editor | runtime\_editor | operations\_editor | project\_owner | project\_editor | project\_viewer |
| ------------------------- | ---------- | ---------------- | --------------- | ------------- | --------------- | ------------------ | -------------- | --------------- | --------------- |
| **Workspace Management**  |            |                  |                 |               |                 |                    |                |                 |                 |
| Create workspace          | ✅          | ❌                | ❌               | ❌             | ❌               | ❌                  | ❌              | ❌               | ❌               |
| Manage workspace users    | ✅          | ✅                | ❌               | ❌             | ❌               | ❌                  | ❌              | ❌               | ❌               |
| Create projects           | ✅          | ✅                | ✅               | ✅             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| **Theme & Media**         |            |                  |                 |               |                 |                    |                |                 |                 |
| Edit themes               | ✅          | ✅                | ❌               | ✅             | ❌               | ❌                  | N/A            | N/A             | N/A             |
| Manage fonts              | ✅          | ✅                | ❌               | ✅             | ❌               | ❌                  | N/A            | N/A             | N/A             |
| Edit media library        | ✅          | ✅                | ❌               | ✅             | ❌               | ❌                  | N/A            | N/A             | N/A             |
| **Runtime Management**    |            |                  |                 |               |                 |                    |                |                 |                 |
| Create builds             | ✅          | ✅                | ❌               | ❌             | ✅               | ❌                  | ✅              | ✅               | ❌               |
| Edit active policy        | ✅          | ✅                | ❌               | ❌             | ✅               | ❌                  | ✅              | ✅               | ❌               |
| Manage config parameters  | ✅          | ✅                | ❌               | ❌             | ✅               | ❌                  | ✅              | ✅               | ❌               |
| **Operations Management** |            |                  |                 |               |                 |                    |                |                 |                 |
| Manage operations         | ✅          | ✅                | ❌               | ❌             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| Edit process instances    | ✅          | ✅                | ✅               | ❌             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| Edit process variables    | ✅          | ✅                | ✅               | ❌             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| **Project Configuration** |            |                  |                 |               |                 |                    |                |                 |                 |
| Edit processes            | ✅          | ✅\*              | ✅\*             | ✅\*           | ✅\*             | ✅\*                | ✅              | ✅               | ❌               |
| Manage templates          | ✅          | ✅\*              | ✅\*             | ✅\*           | ✅\*             | ✅\*                | ✅              | ✅               | ❌               |
| Configure integrations    | ✅          | ✅\*              | ✅\*             | ✅\*           | ✅\*             | ✅\*                | ✅              | ✅               | ❌               |
| **Access Control**        |            |                  |                 |               |                 |                    |                |                 |                 |
| Grant project access      | ✅          | ✅                | ❌               | ❌             | ❌               | ❌                  | ✅              | ❌               | ❌               |
| Manage workspace access   | ✅          | ✅                | ❌               | ❌             | ❌               | ❌                  | ❌              | ❌               | ❌               |

<Note>
  \* Workspace-level roles can only edit project resources for projects they have been explicitly granted access to. Having a workspace role does not automatically grant access to all projects.
</Note>

## Detailed capability breakdown

### Organization-level capabilities

| Capability                       | org\_admin | Notes                                                         |
| -------------------------------- | ---------- | ------------------------------------------------------------- |
| **Workspace Operations**         |            |                                                               |
| Create new workspaces            | ✅          | No limit on number of workspaces                              |
| Edit workspace settings          | ✅          | Can modify any workspace configuration                        |
| Delete workspaces                | ✅          | Permanent deletion with confirmation                          |
| View all workspaces              | ✅          | Unrestricted visibility                                       |
| **User Management**              |            |                                                               |
| Add organization users           | ✅          | Can invite users to organization                              |
| Remove organization users        | ✅          | Can revoke organization access                                |
| Assign organization roles        | ✅          | Can grant org\_admin to other users                           |
| View all user access             | ✅          | Cross-workspace user visibility                               |
| **System Management**            |            |                                                               |
| Configure organization settings  | ✅          | Organization-wide policies                                    |
| Manage global font resources     | ✅          | Fonts available to all workspaces                             |
| Configure out of office policies | ✅          | Organization-level OOO rules                                  |
| **Monitoring**                   |            |                                                               |
| View all audit logs              | ✅          | Organization and workspace level                              |
| Monitor platform status          | ✅          | System health across organization                             |
| Access environment information   | ⚠️         | *Deprecated in 5.7.0.* Configure Environment Info UI removed. |

### Workspace-level capabilities

| Capability                    | workspace\_admin | workspace\_user | theme\_editor | runtime\_editor | operations\_editor | Notes                                       |
| ----------------------------- | ---------------- | --------------- | ------------- | --------------- | ------------------ | ------------------------------------------- |
| **Project Management**        |                  |                 |               |                 |                    |                                             |
| Create projects/libraries     | ✅                | ✅               | ✅             | ✅               | ✅                  | All workspace users can create              |
| View all workspace projects   | ✅                | ❌               | ❌             | ❌               | ❌                  | Only admin sees all projects                |
| Admin access to all projects  | ✅                | ❌               | ❌             | ❌               | ❌                  | Admin has implicit access                   |
| **User & Access Management**  |                  |                 |               |                 |                    |                                             |
| Add workspace users           | ✅                | ❌               | ❌             | ❌               | ❌                  | Admin only                                  |
| Remove workspace users        | ✅                | ❌               | ❌             | ❌               | ❌                  | Admin only                                  |
| Create/manage groups          | ✅                | ❌               | ❌             | ❌               | ❌                  | Admin only                                  |
| Assign workspace roles        | ✅                | ❌               | ❌             | ❌               | ❌                  | Admin only                                  |
| **Design & Branding**         |                  |                 |               |                 |                    |                                             |
| Create themes                 | ✅                | ❌               | ✅             | ❌               | ❌                  | Admin and theme editor                      |
| Edit themes                   | ✅                | ❌               | ✅             | ❌               | ❌                  | Admin and theme editor                      |
| Delete themes                 | ✅                | ❌               | ✅             | ❌               | ❌                  | Admin and theme editor                      |
| Manage fonts                  | ✅                | ❌               | ✅             | ❌               | ❌                  | Admin and theme editor                      |
| Manage media library          | ✅                | ❌               | ✅             | ❌               | ❌                  | Admin and theme editor                      |
| **Runtime Operations**        |                  |                 |               |                 |                    |                                             |
| Create builds                 | ✅                | ❌               | ❌             | ✅               | ❌                  | Admin and runtime editor                    |
| Edit active policies          | ✅                | ❌               | ❌             | ✅               | ❌                  | Admin and runtime editor                    |
| Manage scheduled processes    | ✅                | ❌               | ❌             | ✅               | ❌                  | Admin and runtime editor                    |
| Manage config param overrides | ✅                | ❌               | ❌             | ✅               | ❌                  | Admin and runtime editor                    |
| **Operations Management**     |                  |                 |               |                 |                    |                                             |
| Edit process instances        | ✅                | ✅               | ❌             | ✅               | ✅                  | Admin, user, runtime, and operations editor |
| Edit process variables        | ✅                | ✅               | ❌             | ✅               | ✅                  | Admin, user, runtime, and operations editor |
| Manage operations             | ✅                | ❌               | ❌             | ✅               | ✅                  | Admin, runtime, and operations editor       |
| Create operations             | ✅                | ✅               | ❌             | ✅               | ✅                  | Admin, user, runtime, and operations editor |

### Project-level capabilities

| Capability                 | project\_owner | project\_editor | project\_viewer | Notes                  |
| -------------------------- | -------------- | --------------- | --------------- | ---------------------- |
| **Access Control**         |                |                 |                 |                        |
| Grant project access       | ✅              | ❌               | ❌               | Owner only             |
| Revoke project access      | ✅              | ❌               | ❌               | Owner only             |
| Transfer project ownership | ✅              | ❌               | ❌               | Owner can transfer     |
| **Project Administration** |                |                 |                 |                        |
| Delete project             | ✅              | ❌               | ❌               | Owner only (permanent) |
| Edit project settings      | ✅              | ✅               | ❌               | Owner and editor       |
| Archive project            | ✅              | ❌               | ❌               | Owner only             |
| **Process Design**         |                |                 |                 |                        |
| Create processes           | ✅              | ✅               | ❌               | Owner and editor       |
| Edit processes             | ✅              | ✅               | ❌               | Owner and editor       |
| Delete processes           | ✅              | ✅               | ❌               | Owner and editor       |
| View processes             | ✅              | ✅               | ✅               | All roles can view     |
| Test processes             | ✅              | ✅               | ✅               | All roles can test     |
| **Configuration**          |                |                 |                 |                        |
| Manage enumerations        | ✅              | ✅               | ❌               | Owner and editor       |
| Configure templates        | ✅              | ✅               | ❌               | Owner and editor       |
| Set up integrations        | ✅              | ✅               | ❌               | Owner and editor       |
| Manage workflows           | ✅              | ✅               | ❌               | Owner and editor       |
| Configure UI components    | ✅              | ✅               | ❌               | Owner and editor       |
| **Runtime**                |                |                 |                 |                        |
| Create builds              | ✅              | ✅               | ❌               | Owner and editor       |
| Manage active policies     | ✅              | ✅               | ❌               | Owner and editor       |
| View runtime status        | ✅              | ✅               | ✅               | All roles              |
| **Export & Audit**         |                |                 |                 |                        |
| Export project             | ✅              | ✅               | ❌               | Owner and editor       |
| View audit logs            | ✅              | ✅               | ✅               | All roles              |

## Permission inheritance patterns

### Workspace to project inheritance

<Info>
  Understanding how workspace roles interact with project roles is critical for proper access management.
</Info>

**Key Principles:**

1. **Workspace roles DO NOT automatically grant project access**
   * A user with `workspace_admin` still needs explicit project role to access specific projects
   * Exception: `workspace_admin` can grant themselves access via admin privileges
   * Exception: Users with `projects_admin` permission (included in `workspace_admin`) automatically receive `project_owner` capabilities on all projects in that workspace

2. **Project roles are additive to workspace permissions**
   * User can have `workspace_user` + `project_editor` on specific project
   * Permissions combine (union), not override

3. **Most permissive permission wins**
   * If user has `project_viewer` via one group and `project_editor` via another, they get editor access

4. **Multiple workspace roles can be assigned simultaneously**
   * Users can combine workspace roles for specialized access patterns
   * Example: A user can be both `theme_editor` and `runtime_editor` in the same workspace
   * Permissions from all assigned roles combine (union), enabling flexible role compositions

**Examples:**

```
Scenario 1: Workspace User Creates Project
- User role: workspace_user
- Action: Creates new project "Project X"
- Result: User automatically becomes project_owner of "Project X"

Scenario 2: Workspace Admin Needs Project Access
- User role: workspace_admin
- Action: Wants to edit "Project Y" (not owner)
- Required: Must be granted project_editor or project_owner role on "Project Y"
- Note: Admin can grant themselves this access via admin privileges

Scenario 3: Multiple Role Assignments
- User role: workspace_user
- Project roles: project_viewer on "Project A", project_editor on "Project B"
- Result: Read-only access to Project A, full edit access to Project B

Scenario 4: Mix and Match Roles (Development Environment)
- User roles: theme_editor + runtime_editor
- Context: Development/QA environments where designers and developers need combined access
- Combined capabilities:
  - Full theme management (fonts, media library, theme creation/editing) from theme_editor
  - Runtime operations (create builds, edit policies, manage scheduled processes, config parameters) from runtime_editor
  - Base workspace capabilities (create projects, view workspace resources) from workspace_user inheritance
- Use case: UI/UX developers working in dev environments who need both design and deployment capabilities

Scenario 5: Operations Editor Role
- User role: operations_editor
- Context: Users who need to manage process operations without full runtime access
- Capabilities:
  - Full operations management (migration & move token) across the workspace
  - Edit process instances and process variables
  - Base workspace capabilities (create projects, view workspace resources) from workspace_user inheritance
- Use case: Support engineers or operations teams managing process migrations and token movements
```

### Group-based permission inheritance

**Group Membership Resolution:**

1. User's permissions = Union of (individual permissions + all group permissions)
2. More permissive permission always wins
3. No negative permissions (cannot restrict via groups)

**Example:**

```
User: John
- Individual: project_viewer on Project X
- Group A membership: project_editor on Project X
- Group B membership: workspace_runtime_editor

Result:
- Project X access: project_editor (more permissive than viewer)
- Workspace: workspace_runtime_editor capabilities
- Combined: Full project editing + runtime management
```

## Special permission features

### Read-only view behavior

<Card title="Read-Only Mode Characteristics" icon="eye">
  When a user has read-only permissions (e.g., `project_viewer` role), they experience:

  **Visible but Disabled:**

  * All configuration elements visible but not editable
  * Save buttons hidden or disabled
  * Edit controls grayed out or absent
  * Delete actions not available

  **Available Functionality:**

  * Export operations (where applicable)
  * Audit log access
  * Usage overview and tracking
  * Copy operations to other projects/libraries (for reference)
  * Process and workflow testing through interface

  **UI Indicators:**

  * "View" label instead of "Configure" in contextual menus
  * Read-only badges or indicators
  * No modification prompts or warnings
</Card>

### Bulk permission selection

<Info>
  When configuring custom roles (future feature), bulk selection simplifies permission assignment.
</Info>

**Bulk Selection Categories:**

| Category                  | Applies To                                 | Selectable Operations      |
| ------------------------- | ------------------------------------------ | -------------------------- |
| **Workspace Entities**    | Projects, Themes, Fonts, Media, Audit Logs | Read, Edit, Create, Delete |
| **Access Management**     | Users, Groups, Roles, Platform Status      | Read, Edit, Create, Delete |
| **Runtime Permissions**   | Builds, Policies, Processes, Config Params | Read, Edit, Create, Delete |
| **Project Configuration** | All project resources                      | Read, Edit, Create, Delete |

**How Bulk Selection Works:**

1. Select permission category (e.g., "Workspace Entities")
2. Choose operation level (e.g., "Read")
3. All resources in category receive selected permission
4. Individual permissions can be adjusted afterward
5. Saves time when creating roles with consistent patterns

### Permission dependencies

<Card title="Auto-Included Permissions" icon="link">
  Certain permissions automatically include others to ensure functionality:

  **Workspace Level:**

  * Any workspace permission → automatically includes `workspace_read`
  * Any workspace edit permission → should include `workspace_edit`

  **Project Level:**

  * Any project permission → automatically includes `project_read` (backend)
  * Note: `project_read` not displayed in UI but sent to backend

  **Rationale:**
  Read permissions provide the foundation for all other operations. Without read access, users cannot see resources to edit, create, or delete them.
</Card>

## Related documentation

<CardGroup>
  <Card title="Workspaces Access Rights" icon="shield-check" href="/5.9/setup-guides/access-management/workspaces-access-rights">
    Overview of FlowX workspace access rights and role hierarchy
  </Card>

  <Card title="Permission Reference Guide" icon="book" href="/5.9/setup-guides/access-management/permission-reference-guide">
    Technical implementation details, UI mappings, and naming conventions
  </Card>

  <Card title="Role Selection Guide" icon="compass" href="/5.9/setup-guides/access-management/role-selection-guide">
    Practical guidance for choosing and assigning appropriate roles
  </Card>

  <Card title="Access Management Overview" icon="key" href="/5.9/setup-guides/access-management/access-management-overview">
    Overview of authentication and authorization in FlowX
  </Card>

  <Card title="Configuring IAM Solution" icon="lock" href="/5.9/setup-guides/access-management/configuring-an-iam-solution">
    Setting up identity and access management with Keycloak
  </Card>

  <Card title="Workspaces" icon="briefcase" href="/5.9/docs/projects/workspaces">
    Understanding workspaces and organizing projects
  </Card>
</CardGroup>


# Runtime authorization
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/runtime-authorization

Project-scoped roles, end-user groups, and solution sharing for controlling who can access a published FlowX solution at runtime.

***

## Overview

On FlowX.AI 5.1.x, an end-user role granted access to **every** project and workspace where that role appeared. Enterprise customers needed finer granularity: "this role on this solution, not on every other solution that happens to use the same role name."

5.9.x changes the assignment model. The role itself is still organization-level (defined once, reusable across projects). What's new is **where the role is granted**: on a specific project, through the **Share** modal on a solution.

| 5.1.x                                                    | 5.9.x                                                                                |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Role assigned **directly to user** at organization level | Role assigned to user **in the context of a project** via the solution's Share modal |
| One role grants access on every project that lists it    | Role grants access only on the solutions it has been explicitly shared on            |
| End-user groups managed in Keycloak                      | End-user groups managed in **FlowX** (org-level), assigned to roles on each solution |

The organization-level role catalog and the end-user account model remain in place — see [End-user access management](./end-user-access-management) for managing roles and users at the organization level.

***

## Where roles live

<CardGroup>
  <Card title="Organization" icon="building">
    The role catalog. Roles are created and named once per organization and reusable across all projects and libraries.
  </Card>

  <Card title="Project version (build)" icon="code-branch">
    Each project version carries the list of roles required at runtime. New projects spawn with a default `user` role.
  </Card>

  <Card title="Per resource" icon="route">
    On process swimlanes: which role(s) can view, execute, or self-assign tasks. On UI Flows: which role(s) can interact (UI Flows have a single "interact" permission).
  </Card>
</CardGroup>

<Info>
  **Designer-time vs runtime permissions.** FlowX uses **SpiceDB** for designer-time (build-time) permissions — who can edit which resource in the Designer. Runtime permissions are a separate, custom implementation; SpiceDB does not handle runtime checks because the volume of runtime permission evaluations made the SpiceDB latency unacceptable. Both systems coexist and don't interact at runtime.
</Info>

***

## Sharing a solution

A solution becomes accessible to end users through the **Share** modal on the Solutions page in the generic container app.

<Steps>
  <Step title="Open the Solutions page">
    In the generic container app, open **Solutions**. Each card represents a runtime application backed by a project version.
  </Step>

  <Step title="Open the Share modal">
    On the solution you want to share, click **Share**. The modal shows the roles that the project version exposes at runtime, plus the search inputs for users and groups.
  </Step>

  <Step title="Pick a user or group, then a role">
    Type a name to search. Existing FlowX users appear in the dropdown; you can also invite a brand-new user from the same modal — the user receives a Keycloak invitation email.

    Assign one role per user or group. Repeat per role to give the same user multiple roles.
  </Step>

  <Step title="Save">
    Sharing changes take effect for the next sign-in.
  </Step>
</Steps>

<Warning>
  **Active Policy gotcha.** The Share modal lists only the roles available in the build set as the project's **Active Policy**. If a role is defined in a non-active build (for example, in build 2 while build 1 is active), it does not appear in the modal until that build is promoted to Active Policy.
</Warning>

<Warning>
  **Sharing settings do not export between environments.** When you promote a project to a new environment or workspace, the Share modal assignments are not carried over. Re-configure sharing per environment as part of your deployment checklist.&#x20;
</Warning>

***

## End-user groups

Groups previously managed in Keycloak are now managed inside FlowX. Each group is a named bucket of users; you assign the group to a role on a solution rather than assigning the role to each user individually.

Manage groups under **Organization Settings** → **Access Management** → **End-User Groups**. See [End-user access management](./end-user-access-management#end-users-groups) for the org-level group lifecycle (create, archive, search).

### End-user groups page

The End-User Groups list shows every group in the organization with a **Members** column for the current member count, so it's easy to scan a long list. Click a group to open its detail page, which has two tabs:

<CardGroup>
  <Card title="Members" icon="users">
    The list of end users in the group. Use the **Add Members** action to attach users (search by name or email) and remove members inline. Saving updates the group membership immediately; the next sign-in for those users picks up any solution access changes.
  </Card>

  <Card title="Solution access" icon="share-nodes">
    The list of solutions the group is granted on, plus the role it carries on each. Click **Add Solution Access**, pick a solution, and pick the role to grant. The Active Policy of the chosen solution determines which roles appear in the role dropdown.
  </Card>
</CardGroup>

### Two ways to grant access

Sharing a solution with an end-user group can be done from either side; the resulting permission is the same.

| From                                              | When to use                                                                                                                                           |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solutions page → Share modal** on a solution    | When you want to set up everyone who can use a single solution in one place — typical for app owners reviewing a deployment.                          |
| **End-User Groups → group → Solution access** tab | When you want to set up everything a single group can reach — typical for onboarding a new cohort or an end-user group that spans multiple solutions. |

<Info>
  **Solutions with multiple roles.** When a project version exposes more than one runtime role (for example `user` and `supervisor`), both Share modal entries and Solution access entries let you pick which role to grant to the user or group. Repeat the entry to grant the same group multiple roles on the same solution.
</Info>

### Recommended patterns

<CardGroup>
  <Card title="Single-role solution" icon="user">
    Create one **All End Users** group, give it the `user` role on the solution. Add new end users to the group as they onboard.
  </Card>

  <Card title="Multi-role solution" icon="users">
    Create one group per role on the solution. Add users to the group that matches the access they need. Reuse groups across solutions when the same cohort needs the same access on more than one app.
  </Card>
</CardGroup>

***

## Designer-user bypass

A user with **Designer access to a project** can run that project at runtime without being assigned any runtime role on it.

* Auto-grants **view, execute, and self-assign** on every swimlane in the project.
* The bypass is explicit on purpose: it lets a project's designers run their own work while building, without filing themselves into the runtime role catalog.
* Designer users **cannot** test scenarios "as another runtime role." To verify role-specific behavior, create a test end-user, assign the role to that user via the Share modal, and sign in as that user.

The bypass is implemented through a `designerUser` Keycloak user attribute (boolean) auto-managed at organization provisioning. It is exposed on the access token as the `attributes.designerUser` claim so the engine can decide cheaply whether to apply runtime checks. For environments that block FlowX from administering Keycloak directly, the mapper recipe is in [Configuring an IAM solution → Designer user attribute](./configuring-an-iam-solution#designer-user-attribute).

***

## What stays in Keycloak vs FlowX

| Concern                                                                               | System of record |
| ------------------------------------------------------------------------------------- | ---------------- |
| Authentication, password policy, MFA                                                  | Keycloak         |
| User attributes used by [business filters](../user-roles-management/business-filters) | Keycloak         |
| Federation with external IDPs                                                         | Keycloak         |
| Runtime role catalog                                                                  | FlowX            |
| End-user groups                                                                       | FlowX            |
| Project-scoped role assignment (sharing)                                              | FlowX            |

External IDP federation (per-organization) is configured separately — see [Per-organization IDP federation](#per-organization-idp-federation) below.

***

## Per-organization IDP federation

Enterprise customers typically own their identity provider (Microsoft Entra ID, Okta, Keycloak in another tenancy, AD FS). Rather than managing those users a second time inside FlowX, you can federate the customer's IDP into the **FlowX Keycloak realm for that organization**, so end users sign in with their existing IDP credentials and FlowX picks up their group memberships automatically.

The contract between the federated IDP and FlowX is a set of namespaced claims under `attributes.*` on the FlowX-issued access token. FlowX-specific user data — group memberships, business-filter values, the designer-user flag — all flow through this `attributes` object so that downstream services have a single, predictable read path.

### Token-claim contract

The FlowX access token carries the following claims under the top-level `attributes` object:

| Claim                        | Type               | Required                              | What it carries                                                                                                                                                                          |
| ---------------------------- | ------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attributes.runtimeGroups`   | multivalued string | yes (for federated logins)            | List of FlowX end-user group names the user belongs to. The names must match groups defined under **Organization Settings → Access Management → End-User Groups**.                       |
| `attributes.businessFilters` | multivalued string | only if the org uses business filters | Values of business-filter attributes for the user. See [Business filters](../user-roles-management/business-filters) for how filter values gate which records a runtime user can act on. |
| `attributes.designerUser`    | boolean            | always present                        | `true` when the user has Designer access to the project; FlowX uses this to apply the [designer-user bypass](#designer-user-bypass).                                                     |
| `org_id`                     | string             | always present                        | The organization realm UUID. Hardcoded by Keycloak at organization provisioning.                                                                                                         |

<Info>
  **Behind these claims, on the Keycloak user record:** the `attributes.runtimeGroups` claim is fed by a user attribute named `flowxIdPGroups`; `attributes.businessFilters` is fed by `businessFilter`; `attributes.designerUser` is fed by `designerUser`. Federated logins populate these user attributes automatically through IDP mappers; manual Keycloak setups can write them directly.
</Info>

### How the sync runs

The federation chain is wired with three Keycloak mappers per attribute. Group memberships are the canonical example:

1. **Source IDP claim emitter.** The customer's IDP issues a token containing whatever attribute they maintain — commonly `memberOf`, `groups`, `roles`, or a vendor-specific path.
2. **IDP-to-user-attribute mapper** (on the federated IDP instance inside the FlowX Keycloak realm). Reads the source claim and writes its value into the `flowxIdPGroups` user attribute on the FlowX-side Keycloak user record. In the demo configuration the source claim is `groupsList`, but the source name is customer-specific — you only need to make sure this mapper writes to `flowxIdPGroups`. Set **Sync Mode** to **Force** at both the federated IDP entry and on this mapper so that source-side group changes propagate on every login; the IDP-level setting controls profile resync, the mapper-level setting controls per-attribute resync, and both need to be Force for the per-login refresh customers expect.
3. **User-attribute-to-token-claim mapper** (on the `flowx-platform-authenticate` client). Reads `flowxIdPGroups` from the user record and adds it to the access token as `attributes.runtimeGroups` (multivalued, aggregated). This mapper is **not provisioned automatically**; it has to be added once per organization. See [Runtime groups attribute mapper](./configuring-an-iam-solution#runtime-groups-attribute-mapper) for the setup steps.

The exact same pattern syncs business filters: source IDP claim → `businessFilter` user attribute → `attributes.businessFilters` token claim. The first and last steps are FlowX-managed; only the middle "IDP-to-user-attribute" mapper needs per-customer configuration.

On the **first permission check** after sign-in, FlowX reads `attributes.runtimeGroups` from the token, looks up the matching FlowX end-user groups, and writes the user's membership rows into FlowX's `group_membership` table. Subsequent permission checks read from that table directly.

<Info>
  **Lazy sync, not push.** FlowX does not poll the source IDP and does not implement SCIM. A change to a user's groups in the source IDP only propagates after the user's current FlowX access token expires and they sign in again. Plan token lifetimes accordingly: very long lifetimes mask group changes, very short lifetimes increase auth overhead.
</Info>

<Warning>
  **Sign-out and user-deletion are partial.** Signing out in the source IDP does **not** invalidate the FlowX session. Deleting a user in the source IDP does **not** delete the user record in FlowX Keycloak; the next sign-in attempt will fail at the IDP, but the FlowX-side record persists. Both are intentional: federation maps logins, not the full user lifecycle.
</Warning>

***

## Deployment prerequisites

The first time the data-sync job runs against a 5.9.0 environment, it provisions FlowX-managed end-user groups and runtime roles in Keycloak. Configure Keycloak admin credentials on the data-sync job (`FLOWX_OPENID_PROVIDER`, `FLOWX_OPENID_SERVERURL`, `FLOWX_OPENID_USER`, `FLOWX_OPENID_PASSWORD`, `FLOWX_OPENID_CLIENTID`) before deploying — see [Data-sync job setup → OpenID provider configuration](../data-sync#openid-provider-configuration).

***

## Migration notes

If you upgrade from 5.1.x with existing role-on-user assignments, those assignments continue to work. New solutions and new role assignments use the project-scoped model.

End-user groups previously managed in Keycloak are created in FlowX automatically by the data-sync Liquibase migration on first boot — no manual recreation required. Confirm the migrated group list under **Organization Settings → Access Management → End-User Groups** after the upgrade and adjust as needed.

For details on the end-user group + runtime-role transition during a 5.1.x → 5.9.x upgrade, see [Runtime authorization migration](/5.9/migrating-from-5.1-lts/runtime-authorization).

***

## Related resources

<CardGroup>
  <Card title="End-user access management" icon="user-group" href="./end-user-access-management">
    Org-level end-user, role, and group management
  </Card>

  <Card title="Workspaces access rights" icon="key" href="./workspaces-access-rights">
    Designer-side access to workspaces and projects
  </Card>

  <Card title="Roles & permissions matrix" icon="table" href="./roles-permissions-matrix">
    Full matrix of designer and end-user roles
  </Card>

  <Card title="Configuring access roles for processes" icon="diagram-project" href="../flowx-engine-setup-guide/configuring-access-roles-for-processes">
    Per-swimlane role configuration on process definitions
  </Card>
</CardGroup>


# Workspaces access rights
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/workspaces-access-rights

Overview of FlowX workspaces access rights and role-based access control

<Note>
  **Documentation Navigation:**

  * **Workspaces Access Rights** (Current) - Role overview and concepts
  * [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) - Detailed permission specifications
  * [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide) - Technical implementation details
  * [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide) - Practical scenarios and best practices
</Note>

<Info>
  FlowX provides a comprehensive role-based access control system with predefined roles at organization, workspace, and project levels.
</Info>

## Overview of workspaces access rights

FlowX provides a structured role hierarchy designed to support multi-tenant workspace architecture while maintaining security and governance. The system includes predefined roles that cannot be modified, ensuring consistent access patterns across all FlowX deployments.

<Frame>
  ![Default Roles Hierarchy](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/default_roles.png)
</Frame>

## Authentication and authorization architecture

FlowX separates authentication and authorization into distinct systems:

<Tabs>
  <Tab title="Authentication (Keycloak)">
    **Handles user identity and login**

    * User login and identity verification
    * Token generation for authenticated users
    * User creation and management in identity provider
    * Service account identification with `SA_FLOWX` role
  </Tab>

  <Tab title="Authorization (CAS/auth-system)">
    **Manages access control and permissions**

    * Endpoint access control within FlowX Designer
    * Workspace and project permissions
    * Role and group management
    * ACL-based fine-grained access control
    * Database-stored permissions for better performance
  </Tab>
</Tabs>

<Note>
  **Designer vs Runtime Permissions**

  * **Designer Permissions**: Control access to FlowX Designer interface, managed through workspaces and the role system
  * **Runtime Permissions**: Control process execution and data access, managed through Keycloak roles

  All roles and permissions described in this document apply only to FlowX Designer access.
</Note>

## Configuration and Runtime access

<CardGroup>
  <Card title="Configuration Access" icon="wrench">
    **Project-level roles for design and building**

    * Process and workflow design
    * UI templates and integrations
    * Project settings and resources
    * **Roles**: Owner, Editor, Viewer
    * **Scope**: Per-project assignment
  </Card>

  <Card title="Runtime Access" icon="play">
    **Workspace-level roles for deployment and execution**

    * Build creation and deployment
    * Process instance management
    * Scheduled processes and policies
    * Runtime environment overrides
    * **Roles**: Runtime Editor, Admin
    * **Scope**: Workspace-wide application
  </Card>
</CardGroup>

<Warning>
  **Key Distinction**: Project roles provide **configuration access only**. Runtime operations require separate workspace-level roles like `workspace_runtime_editor`, `workspace_admin` or `workspace_user`, etc.
</Warning>

## User types

FlowX distinguishes between two primary user types, each with different access patterns and authentication requirements:

### Designer users

<Card title="Designer Users" icon="pencil">
  **Users who access FlowX Designer to configure and manage applications**

  **Characteristics:**

  * Created in FlowX database upon first login to Designer
  * Managed through the workspace and role system described in this document
  * Authentication handled by external provider (e.g., Keycloak)
  * Authorization controlled by FlowX Designer roles and permissions

  **Use Cases:**

  * Platform administrators
  * Business analysts and configurators
  * Process designers and developers
  * UI/UX designers and theme editors
</Card>

### Runtime users

<Card title="Runtime Users" icon="user-group">
  **Users who interact with applications built using FlowX, but do not necessarily have access to FlowX Designer**

  **Characteristics:**

  * Not created in FlowX database unless they also log into FlowX Designer
  * Receive access to applications powered by FlowX via runtime roles and groups from external authentication system (e.g., Keycloak)
  * Permissions at runtime (e.g., swimlane access, task management) are granted based on roles/groups parsed from user's access token
  * No visibility in Designer unless they have both runtime and Designer access

  **Subtypes:**

  <AccordionGroup>
    <Accordion title="Business Users (Operational Staff)" icon="briefcase">
      **Internal staff using FlowX-powered applications**

      * Bank tellers, loan officers, branch staff
      * Customer service representatives
      * Back-office operational teams
      * Task management and workflow execution capabilities
      * Access granted through organizational roles and group memberships
    </Accordion>

    <Accordion title="End Users (Customers)" icon="users">
      **Organization's customers interfacing with customer-facing applications**

      * External customers using digital banking, insurance, or other services
      * Indirect users of FlowX runtime via organization's digital channels
      * Typically authenticated through customer identity systems
      * Limited to self-service and customer-facing workflows
    </Accordion>
  </AccordionGroup>
</Card>

<Warning>
  **User Overlap Between Designer and Runtime**

  Users can have both Designer access and Runtime access simultaneously. When this occurs:

  * The user is created in FlowX database with Designer roles and permissions
  * The same user can also interact with runtime applications using their runtime roles from Keycloak
  * Designer permissions control what they can configure in FlowX Designer
  * Runtime permissions control what processes and tasks they can access in deployed applications
</Warning>

<Info>
  **Organization ID propagation**

  FlowX propagates the organization ID across runtime contexts for multi-tenant isolation:

  * **Scheduler execution**: Organization ID added to scheduled job context
  * **Event listeners**: Organization ID propagated to event handlers
  * **Process instances**: Organization ID captured from the initiator

  This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
</Info>

## Role architecture

<CardGroup>
  <Card title="Organization Level" icon="building">
    Cross-workspace administrative access for managing the entire FlowX organization

    **Roles:**

    * Organization Admin
  </Card>

  <Card title="Workspace Level" icon="users">
    Workspace-specific roles for managing resources, users, and configurations within a workspace

    **Roles:**

    * Workspace Admin
    * Workspace User
    * Theme Editor
    * Workspace Runtime Editor
    * Workspace Operations Editor
  </Card>

  <Card title="Project Level" icon="folder">
    Project-specific roles for controlling access to individual projects and their resources

    **Roles:**

    * Project Owner
    * Project Editor
    * Project Viewer
  </Card>
</CardGroup>

## Organization level roles

### Organization admin

<Card title="Organization Admin" icon="crown">
  **Full administrative access across the entire FlowX organization**

  **Key Responsibilities:**

  * Managing all workspaces across the organization
  * Creating and organizing workspace structure
  * Managing organization-wide users and groups
  * Overseeing system health and platform status
  * Implementing organization-wide policies and configurations

  **Key Characteristics:**

  * Cannot be edited, duplicated, or deleted
  * Can only be assigned in the Organization admin interface
  * Hidden from workspace role lists
  * Highest level of access in the FlowX hierarchy
  * Should be limited to 2-3 trusted platform administrators

  **Use Cases:**

  * Platform administrators managing FlowX deployment
  * IT managers responsible for multi-workspace environments
  * System architects overseeing enterprise FlowX usage
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Organization Management">
    ✅ Create, edit, and delete workspaces\
    ✅ Configure organization settings\
    ✅ Manage organization-wide users and groups\
    ✅ Access all projects across all workspaces
  </Tab>

  <Tab title="System Management">
    ✅ Manage global font resources\
    ✅ Configure out of office policies\
    ✅ Monitor platform status
    ⚠️ Manage environment information *(deprecated in 5.7.0 — Configure Environment Info UI removed)*
  </Tab>

  <Tab title="Monitoring">
    ✅ View organization audit logs\
    ✅ Access all workspace audit logs\
    ✅ Monitor system health across organization\
    ❌ Cannot edit or delete audit entries (read-only)
  </Tab>
</Tabs>

<Warning>
  **Critical Security Note**

  The Organization Admin role should be assigned sparingly. Organization admins have access to **all projects in all workspaces** without exception. Limit this role to trusted platform administrators only.
</Warning>

<Tip>
  For complete permission specifications, see the [Organization Admin Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#organization-admin-permission-matrix).
</Tip>

## Workspace level roles

### Workspace admin

<Card title="Workspace Admin" icon="shield-check">
  **Complete control over workspace-level resources and users**

  **Key Responsibilities:**

  * Managing workspace users, groups, and roles
  * Overseeing all projects within the workspace
  * Configuring workspace themes and branding
  * Managing workspace-level settings and policies
  * Handling workspace resource allocation
  * Granting and revoking project access

  **Key Characteristics:**

  * Cannot be edited or deleted (predefined role)
  * Can be assigned to users and groups within the workspace
  * Listed in workspace role management interfaces
  * Cannot manage organization-wide settings
  * Has admin access to all projects in their workspace

  **Use Cases:**

  * Business unit managers
  * Department heads overseeing team projects
  * Workspace administrators with full workspace responsibility
  * Team leads managing workspace access and resources
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Workspace Management">
    ✅ Create projects and libraries\
    ✅ Manage workspace themes and fonts\
    ✅ Manage global media library\
    ✅ Configure workspace settings\
    ✅ View workspace audit logs
  </Tab>

  <Tab title="User Management">
    ✅ Add and remove workspace users\
    ✅ Create and manage groups\
    ✅ Assign workspace roles\
    ✅ Manage user permissions\
    ❌ Cannot create or delete workspaces
  </Tab>

  <Tab title="Runtime Management">
    ✅ Create and view builds\
    ✅ Manage active policies\
    ✅ Configure scheduled processes\
    ✅ Manage configuration parameter overrides\
    ✅ View and edit process instances
    ✅ Edit process variables on active instances
  </Tab>
</Tabs>

<Tip>
  For complete permission specifications, see the [Workspace Admin Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-admin-permission-matrix).
</Tip>

### Workspace user

<Card title="Workspace User" icon="user">
  **Standard workspace access with project creation capabilities**

  **Key Responsibilities:**

  * Creating new projects within the workspace
  * Working on assigned projects with appropriate project-level roles
  * Viewing workspace resources (themes, fonts, media)
  * Basic workspace participation

  **Key Characteristics:**

  * Cannot be edited or deleted (predefined role)
  * Default role for most workspace members
  * Can create projects (becomes project owner automatically)
  * Needs explicit project access to work on others' projects
  * Limited administrative capabilities

  **Use Cases:**

  * Business analysts and configurators
  * Process designers and developers
  * Junior team members
  * Team members who build projects within defined boundaries
  * General workspace members
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Workspace Access">
    ✅ Create projects and libraries\
    ✅ View workspace themes (read-only)\
    ✅ View workspace fonts (read-only)\
    ✅ View global media library (read-only)\
    ✅ View workspace users, groups, and roles (read-only)\
    ❌ Cannot manage workspace settings
  </Tab>

  <Tab title="Runtime Access">
    ✅ View builds for accessible projects\
    ✅ View active policies (read-only)\
    ✅ View scheduled processes (read-only)\
    ✅ View configuration parameters (read-only)\
    ✅ View process instances for accessible projects (read-only)\
    ❌ Cannot create or modify runtime configurations
  </Tab>

  <Tab title="Project Access">
    ✅ Create new projects (becomes owner)\
    ✅ Access granted projects based on project role (read-only)\
    ❌ Cannot view all workspace projects by default\
    ❌ Needs explicit project access from project owner (read-only)
  </Tab>
</Tabs>

<Tip>
  For complete permission specifications, see the [Workspace User Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-user-permission-matrix).
</Tip>

### Theme editor

<Card title="Theme Editor" icon="palette">
  **Specialized role for visual design and branding management**

  **Key Responsibilities:**

  * Designing and customizing application themes
  * Managing workspace fonts and typography
  * Organizing and maintaining media library
  * Creating visual design assets
  * Ensuring brand consistency across projects

  **Key Characteristics:**

  * Extends workspace\_user with design permissions
  * Same base permissions as workspace\_user
  * Additional permissions for visual asset management
  * Cannot be edited or deleted (predefined role)
  * Focused on design and branding elements

  **Use Cases:**

  * UI/UX designers
  * Brand managers ensuring visual consistency
  * Visual design specialists
  * Marketing team members managing brand assets
  * Design teams customizing FlowX applications
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Design Management">
    ✅ Create, edit, and delete themes\
    ✅ Manage workspace fonts (full access)\
    ✅ Manage global media library\
    ✅ Set default themes\
    ✅ Configure theme sections
  </Tab>

  <Tab title="Inherited from Workspace User">
    ✅ Create projects and libraries\
    ✅ View workspace resources\
    ✅ View runtime information (read-only)\
    ✅ Standard workspace user capabilities
  </Tab>
</Tabs>

<Note>
  Theme editors have the same project access rules as workspace users. They can create projects but need explicit access to work on others' projects.
</Note>

<Tip>
  For complete permission specifications, see the [Theme Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#theme-editor-permission-matrix).
</Tip>

### Workspace runtime editor

<Card title="Workspace Runtime Editor" icon="gear">
  **Extended workspace user role with runtime configuration capabilities**

  **Key Responsibilities:**

  * Creating and managing workspace builds
  * Configuring runtime environments and deployments
  * Managing active policies and deployment strategies
  * Overriding configuration parameters for runtime
  * Monitoring and managing process instances
  * Scheduling process executions

  **Key Characteristics:**

  * Extends workspace\_user with runtime permissions
  * Same base permissions as workspace\_user
  * Additional permissions for runtime environment management
  * Cannot be edited or deleted (predefined role)
  * Focused on deployment and runtime operations

  **Use Cases:**

  * DevOps engineers managing deployments
  * Release managers handling build processes
  * Runtime environment administrators
  * Technical operations staff
  * System administrators with runtime responsibilities
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Runtime Management">
    ✅ Create builds from library versions\
    ✅ Edit active policies\
    ✅ Manage scheduled processes (activate, deactivate, delete)\
    ✅ Create, edit, and delete configuration parameter overrides\
    ✅ Edit process instances
  </Tab>

  <Tab title="Inherited from Workspace User">
    ✅ Create projects and libraries\
    ✅ View workspace resources\
    ✅ Standard workspace user capabilities
  </Tab>
</Tabs>

<Warning>
  **Runtime access is workspace-scoped**

  Runtime permissions are managed at the workspace level, not the project level. Users with workspace\_runtime\_editor can manage runtime configurations across **all projects in the workspace**, not just specific projects.
</Warning>

<Tip>
  For complete permission specifications, see the [Workspace Runtime Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-runtime-editor-permission-matrix).
</Tip>

### Workspace operations editor

<Card title="Workspace Operations Editor" icon="rotate">
  **Extended workspace user role with operations management capabilities**

  **Key Responsibilities:**

  * Managing process instance operations (migration & move token)
  * Editing process variables on active instances
  * Managing operational tasks across the workspace
  * Viewing and editing process instances

  **Key Characteristics:**

  * Extends workspace\_user with operations permissions
  * Same base permissions as workspace\_user
  * Additional permissions for operations management
  * Cannot be edited or deleted (predefined role)
  * Focused on process operations and instance management

  **Use Cases:**

  * Support engineers managing process migrations
  * Operations teams handling token movements
  * Technical support staff editing process variables
  * Operations managers overseeing process instances
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Operations Management">
    ✅ Create, view, edit, and delete operations (migration & move token)\
    ✅ Edit process instances\
    ✅ Edit process variables on active instances\
    ✅ View all process instances across workspace
  </Tab>

  <Tab title="Inherited from Workspace User">
    ✅ Create projects and libraries\
    ✅ View workspace resources\
    ✅ Standard workspace user capabilities
  </Tab>
</Tabs>

<Note>
  The workspace\_operations\_editor role provides focused permissions for operations management without the broader runtime capabilities of workspace\_runtime\_editor.
</Note>

<Tip>
  For complete permission specifications, see the [Workspace Operations Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix).
</Tip>

## Project level roles

### Project owner

<Card title="Project Owner" icon="crown">
  **Complete ownership and governance of project resources**

  **Key Responsibilities:**

  * Full project governance and decision-making authority
  * Granting and revoking project access to other users
  * Managing all project configurations and resources
  * Approving major project changes
  * Overseeing project lifecycle

  **Key Characteristics:**

  * Automatically assigned to project creator
  * Cannot be edited, duplicated, deleted, or manually assigned through UI
  * Hidden from role selection interfaces
  * System-managed role with highest project-level access
  * Permanent assignment for project lifecycle
  * Only one owner per project

  **Automatic Assignment:**

  * Automatically granted when creating a project
  * Can be transferred to another user (ownership transfer)
  * Cannot be removed without transferring to another user

  **Use Cases:**

  * Project leads with full authority
  * Technical architects owning project decisions
  * Product owners managing project direction
  * Users who created the project
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Project Administration">
    ✅ Complete project ownership and governance\
    ✅ Grant/revoke project access\
    ✅ Delete project\
    ✅ Transfer project ownership\
    ✅ Full administrative control
  </Tab>

  <Tab title="Configuration">
    ✅ All configuration resources (full access)\
    ✅ Processes, workflows, enumerations\
    ✅ Templates, media, integrations\
    ✅ AI agents, reusable resources\
    ✅ All project settings
  </Tab>
</Tabs>

<Note>
  **Non-Configurable Permissions**

  Project owner permissions are not configurable in the UI. The role automatically includes all project-level permissions without exception.
</Note>

<Tip>
  For complete permission specifications, see the [Project Owner Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#project-owner-permission-matrix).
</Tip>

### Project editor

<Card title="Project Editor" icon="pen-to-square">
  **Full project configuration and management capabilities**

  **Key Responsibilities:**

  * Building and configuring project processes
  * Designing workflows and integrations
  * Creating UI configurations
  * Managing project resources
  * Creating builds and deployments
  * Day-to-day project development

  **Key Characteristics:**

  * Can be assigned to users and groups
  * Comprehensive project access without ownership rights
  * Cannot grant/revoke project access to others
  * Standard role for project team members
  * Cannot be edited or deleted (predefined role)

  **Use Cases:**

  * Senior developers and configurators
  * Technical leads on project teams
  * Business analysts with advanced permissions
  * Team members with full project configuration needs
  * Development team members
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="Configuration">
    ✅ All configuration resources (full access)\
    ✅ Processes, workflows, enumerations\
    ✅ Templates, media, integrations\
    ✅ AI agents, reusable resources\
    ✅ All project settings\
    ❌ Cannot manage project access
  </Tab>

  <Tab title="Limitations">
    ❌ Cannot grant/revoke project access\
    ❌ Cannot delete project\
    ❌ No administrative rights over project
  </Tab>
</Tabs>

<Tip>
  For complete permission specifications, see the [Project Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#project-editor-permission-matrix).
</Tip>

### Project viewer

<Card title="Project Viewer" icon="eye">
  **Read-only access to project configuration and settings**

  **Key Responsibilities:**

  * Reviewing project configurations
  * Auditing processes and workflows
  * Compliance checking and documentation
  * Understanding project structure for training
  * Monitoring project status

  **Key Characteristics:**

  * Can be assigned when granting project access
  * Completely read-only access
  * Safe role for stakeholders needing visibility
  * No modification capabilities
  * Can test processes through interface
  * Suitable for audit and review purposes

  **Use Cases:**

  * Business stakeholders and executives
  * Quality assurance team members
  * External consultants needing project visibility
  * Audit and compliance personnel
  * New team members during onboarding
  * Documentation and training purposes
</Card>

#### Key permissions summary

<Tabs>
  <Tab title="View Access">
    ✅ View all configuration resources\
    ✅ View processes, workflows, enumerations\
    ✅ View templates, media, integrations\
    ✅ View project settings and dependencies\
    ✅ Export project resources
    ✅ Test processes and workflows
  </Tab>

  <Tab title="Restrictions">
    ❌ Cannot edit any resources
    ❌ Cannot create any resources\
    ❌ Cannot delete any resources\
    ❌ Cannot modify configurations\
    ❌ Cannot create builds or deployments
  </Tab>
</Tabs>

<Info>
  **Testing Capability**

  Project viewers can test processes and workflows through the interface, allowing them to understand how processes work without the ability to modify configurations.
</Info>

<Tip>
  For complete permission specifications, see the [Project Viewer Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#project-viewer-permission-matrix).
</Tip>

## Role comparison matrix

### Quick capability comparison

The following table provides a high-level comparison of key capabilities across all roles:

| Capability                | org\_admin | workspace\_admin | workspace\_user | theme\_editor | runtime\_editor | operations\_editor | project\_owner | project\_editor | project\_viewer |
| ------------------------- | ---------- | ---------------- | --------------- | ------------- | --------------- | ------------------ | -------------- | --------------- | --------------- |
| **Workspace Management**  |            |                  |                 |               |                 |                    |                |                 |                 |
| Create workspace          | ✅          | ❌                | ❌               | ❌             | ❌               | ❌                  | ❌              | ❌               | ❌               |
| Manage workspace users    | ✅          | ✅                | ❌               | ❌             | ❌               | ❌                  | ❌              | ❌               | ❌               |
| Create projects           | ✅          | ✅                | ✅               | ✅             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| **Design & Branding**     |            |                  |                 |               |                 |                    |                |                 |                 |
| Edit themes               | ✅          | ✅                | ❌               | ✅             | ❌               | ❌                  | N/A            | N/A             | N/A             |
| Manage fonts              | ✅          | ✅                | ❌               | ✅             | ❌               | ❌                  | N/A            | N/A             | N/A             |
| **Runtime Operations**    |            |                  |                 |               |                 |                    |                |                 |                 |
| Create builds             | ✅          | ✅                | ❌               | ❌             | ✅               | ❌                  | ✅              | ✅               | ❌               |
| Edit active policy        | ✅          | ✅                | ❌               | ❌             | ✅               | ❌                  | ✅              | ✅               | ❌               |
| Manage config parameters  | ✅          | ✅                | ❌               | ❌             | ✅               | ❌                  | ✅              | ✅               | ❌               |
| **Operations Management** |            |                  |                 |               |                 |                    |                |                 |                 |
| Manage operations         | ✅          | ✅                | ❌               | ❌             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| Edit process variables    | ✅          | ✅                | ✅               | ❌             | ✅               | ✅                  | N/A            | N/A             | N/A             |
| **Project Configuration** |            |                  |                 |               |                 |                    |                |                 |                 |
| Edit processes            | ✅          | ✅\*              | ✅\*             | ✅\*           | ✅\*             | ✅\*                | ✅              | ✅               | ❌               |
| Manage templates          | ✅          | ✅\*              | ✅\*             | ✅\*           | ✅\*             | ✅\*                | ✅              | ✅               | ❌               |
| Configure integrations    | ✅          | ✅\*              | ✅\*             | ✅\*           | ✅\*             | ✅\*                | ✅              | ✅               | ❌               |
| **Access Control**        |            |                  |                 |               |                 |                    |                |                 |                 |
| Grant project access      | ✅          | ✅                | ❌               | ❌             | ❌               | ❌                  | ✅              | ❌               | ❌               |
| Manage workspace access   | ✅          | ✅                | ❌               | ❌             | ❌               | ❌                  | ❌              | ❌               | ❌               |

<Note>
  \* Workspace-level roles can only edit project resources for projects they have been explicitly granted access to. Having a workspace role does not automatically grant access to all projects.
</Note>

## Default groups

### Everyone in workspace group

<Info>
  Every workspace automatically includes a special system-managed group for simplified access management to all workspace users.
</Info>

<Card title="all_users_[workspace_name]" icon="users">
  **Display Name:** Everyone from \<workspace name>

  **Purpose:**
  Provides convenient access management for all users associated with a workspace, enabling efficient bulk access grants.

  **Automatic Behavior:**

  * ✅ Created automatically during workspace provisioning
  * ✅ Users automatically added when granted workspace access
  * ✅ Users automatically removed when workspace access revoked
  * ✅ Pre-selected when creating new projects/libraries
  * ✅ Appears in user/group search results
  * ❌ Cannot be edited, deleted, or duplicated
  * ❌ Membership cannot be manually modified

  **Common Use Cases:**

  * Grant all workspace members read access to reference projects
  * Provide baseline visibility across workspace projects
  * Simplify onboarding by giving new users automatic access to shared resources
  * Create workspace-wide shared libraries

  **Example:**

  ```
  Workspace: "Product Development"
  Group: "all_users_product_development"
  Display: "Everyone from Product Development"
  ```
</Card>

<Warning>
  **No Individual Exclusions**

  The "Everyone in workspace" group includes ALL workspace members without exception. You cannot remove specific users from this group or create exclusions. If you need selective access, create custom groups instead.
</Warning>

### Custom groups

<AccordionGroup>
  <Accordion title="Creating Custom Groups" icon="plus">
    **When to create custom groups:**

    * Team-based access (e.g., "Development Team", "QA Team")
    * Role-based access (e.g., "Senior Developers", "Stakeholders")
    * Project-specific access (e.g., "Project Alpha Team")
    * Cross-functional teams (e.g., "Release Management")

    **Group naming best practices:**

    * Use descriptive names indicating purpose
    * Follow consistent naming conventions
    * Example format: `[function]_[department]_[sub-group]`
    * Good examples: `dev_team_frontend`, `stakeholders_finance`, `editors_project_phoenix`
  </Accordion>

  <Accordion title="Managing Groups" icon="users">
    **Group operations:**

    * Add members individually or bulk import
    * Assign workspace-level roles to groups
    * Use groups when granting project access
    * Remove members or delete entire groups

    **Best practices:**

    * Use groups instead of individual assignments when possible
    * Document group purposes clearly
    * Review group memberships regularly
    * Plan group structure before implementation
  </Accordion>
</AccordionGroup>

<Tip>
  For comprehensive groups documentation and strategies, see the [Role Selection & Management Guide](/5.9/setup-guides/access-management/role-selection-guide#groups-and-access-management).
</Tip>

## Quick start guide

### Grant workspace access

<Steps>
  <Step title="Navigate to workspace users">
    Go to your workspace → Access Management → Users
  </Step>

  <Step title="Add user">
    Click "Add" button → Search for user by name or email
  </Step>

  <Step title="Assign role">
    Select appropriate role (typically `workspace_user` for standard access) → Confirm
  </Step>
</Steps>

### Assign user to project

<Steps>
  <Step title="Open project access management">
    Go to project → Settings → Access Management
  </Step>

  <Step title="Grant access">
    Click "Grant Access" → Search for user or group
  </Step>

  <Step title="Select role">
    Choose role (`project_editor` for full access, `project_viewer` for read-only) → Confirm
  </Step>
</Steps>

### Create a custom group

<Steps>
  <Step title="Navigate to groups">
    Go to workspace → Access Management → Groups
  </Step>

  <Step title="Create group">
    Click "Add" → Enter descriptive group name and description
  </Step>

  <Step title="Add members and assign role">
    Add users to group → Assign workspace-level role to group → Save
  </Step>
</Steps>

## Legacy role migration

### FlowX 4.x to 5.0 role mapping

<Warning>
  FlowX 4.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required in FlowX 5.0.
</Warning>

| FlowX 4.x Role        | FlowX 5.0 Equivalent                 | Scope Change         | Notes                           |
| --------------------- | ------------------------------------ | -------------------- | ------------------------------- |
| `FLOWX_ADMIN`         | `workspace_admin`                    | Now workspace-scoped | Was global, now per-workspace   |
| `FLOWX_CONFIGURATOR`  | `workspace_user` or `project_editor` | Depends on needs     | Choose based on required access |
| `FLOWX_UI_DESIGNER`   | `theme_editor`                       | Workspace-scoped     | Enhanced capabilities           |
| `FLOWX_VIEWER`        | `project_viewer`                     | Now project-specific | Was global, now per-project     |
| Custom Keycloak roles | Manual review required               | N/A                  | Assess against new structure    |

### Key migration considerations

<CardGroup>
  <Card title="Scope Changes" icon="sitemap">
    Roles are now workspace-scoped rather than global. Reassign within workspace context.
  </Card>

  <Card title="Runtime Permissions" icon="server">
    Runtime permissions moved to workspace level. Use `workspace_runtime_editor` role.
  </Card>

  <Card title="Database Storage" icon="database">
    Roles now stored in FlowX database for better performance and control.
  </Card>

  <Card title="Hierarchy Changes" icon="layer-group">
    New role hierarchy requires review of user access patterns.
  </Card>
</CardGroup>

## Best practices summary

<CardGroup>
  <Card title="Start Conservative" icon="shield-check">
    Begin with minimum required access (e.g., `project_viewer`) and escalate as needed based on demonstrated requirements.
  </Card>

  <Card title="Use Groups" icon="users">
    Create and use groups for teams and functions rather than managing individual user access.
  </Card>

  <Card title="Regular Reviews" icon="calendar-check">
    Conduct quarterly access reviews, remove inactive users, and validate permissions match responsibilities.
  </Card>

  <Card title="Document Decisions" icon="file-text">
    Maintain records of role assignments, especially for elevated privileges and exceptions.
  </Card>

  <Card title="Principle of Least Privilege" icon="lock">
    Always grant the minimum permissions necessary for users to perform their job functions.
  </Card>

  <Card title="Plan for Transitions" icon="arrows-rotate">
    Have clear processes for role changes, project ownership transfers, and access removal.
  </Card>
</CardGroup>

<Tip>
  For detailed best practices and practical scenarios, see the [Role Selection & Management Guide](/5.9/setup-guides/access-management/role-selection-guide#best-practices-summary).
</Tip>

## Current limitations in FlowX 5.1

<Warning>
  The following features have specific limitations in FlowX 5.1:
</Warning>

**Role Management:**

* Custom roles not available
* Bulk role assignment tools not available

**Workspace Features:**

* Workspace deletion functionality not available
* Moving projects/libraries between workspaces not supported

**Integration Features:**

* Runtime roles and groups will return errors if Keycloak isn't used as the authentication provider

## Troubleshooting common issues

<AccordionGroup>
  <Accordion title="User Cannot Access Workspace" icon="ban">
    **Possible Causes:**

    * User not assigned to workspace
    * No role assigned in workspace
    * User not in any workspace groups

    **Solutions:**

    1. Verify user is in workspace user list
    2. Check role assignments
    3. Validate group memberships
    4. Contact workspace administrator for access
  </Accordion>

  <Accordion title="Cannot See Project" icon="eye-slash">
    **Possible Causes:**

    * No project-level access granted
    * Workspace role doesn't auto-grant project access
    * Project visibility restrictions

    **Solutions:**

    1. Contact project owner for access
    2. Verify workspace membership
    3. Check if project exists in current workspace
    4. Request appropriate project role
  </Accordion>

  <Accordion title="Permissions Not Working After Assignment" icon="key">
    **Possible Causes:**

    * Cached permissions not updated
    * User hasn't logged out and back in
    * Conflicting role assignments

    **Solutions:**

    1. Log out completely and log back in
    2. Clear browser cache
    3. Wait a few minutes for permissions to propagate
    4. Contact workspace administrator if issue persists
  </Accordion>
</AccordionGroup>

<Tip>
  For comprehensive troubleshooting with detailed diagnostic procedures, see [Troubleshooting Permission Issues](/5.9/setup-guides/access-management/role-selection-guide#troubleshooting-permission-issues).
</Tip>

## Related documentation

<CardGroup>
  <Card title="Complete Permissions Matrix" icon="table" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    Detailed permission specifications for all FlowX roles with comprehensive matrices
  </Card>

  <Card title="Permission Reference Guide" icon="book" href="/5.9/setup-guides/access-management/permission-reference-guide">
    Technical implementation details, UI mappings, and permission naming conventions
  </Card>

  <Card title="Role Selection Guide" icon="compass" href="/5.9/setup-guides/access-management/role-selection-guide">
    Practical scenarios, best practices, troubleshooting, and migration guidance
  </Card>

  <Card title="Access Management Overview" icon="key" href="/5.9/setup-guides/access-management/access-management-overview">
    Overview of FlowX access management system and authentication architecture
  </Card>

  <Card title="Configuring IAM Solution" icon="lock" href="/5.9/setup-guides/access-management/configuring-an-iam-solution">
    Setting up identity and access management with Keycloak
  </Card>

  <Card title="Workspaces" icon="briefcase" href="/5.9/docs/projects/workspaces">
    Understanding workspaces and their role in organizing projects
  </Card>
</CardGroup>


# AI Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/ai-gateway-setup

Set up the AI Gateway microservice — powers the AI chat experience in the FlowX Designer, streaming AI assistant responses to the browser and routing requests to the config-time agents.

<Info>
  The AI Gateway is a core service that owns the Designer AI chat surface. It streams AI assistant responses to the browser over Server-Sent Events (SSE) and routes chat requests to the config-time agents.
</Info>

## Dependencies

Before setting up the AI Gateway, ensure you have the following dependencies in place:

* **MongoDB** for storing conversation context
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained, workspace-level authorization on AI interactions
* **AI Platform** — the config-time agents the gateway routes chat requests to

## Infrastructure prerequisites

| Component   | Description                                    |
| ----------- | ---------------------------------------------- |
| MongoDB     | Stores AI chat conversation context            |
| Keycloak    | Identity provider for service authentication   |
| SpiceDB     | Authorization service for workspace validation |
| AI Platform | Config-time agents that handle chat requests   |

***

## Configuration

### Authorization configuration

The AI Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                   | Description                                                           | Default Value                                                                                      |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                        | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                        | Base URL of the Keycloak server                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                              | Service-accounts realm ID                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`              | URL of the organization-manager service, used by the security library | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`     | Service account client ID                                             | `flowx-ai-gateway-sa`                                                                              |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued)                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`     | Provider token URI, resolved against the service-accounts realm       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

***

### MongoDB configuration

| Environment Variable      | Description            | Default Value |
| ------------------------- | ---------------------- | ------------- |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | -             |

***

### CAS lib configuration (SpiceDB)

| Environment Variable                         | Description                                                                                        | Default Value |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`                         | SpiceDB hostname                                                                                   | `spicedb`     |
| `FLOWX_SPICEDB_PORT`                         | SpiceDB gRPC port                                                                                  | `50051`       |
| `FLOWX_SPICEDB_TOKEN`                        | SpiceDB authentication token                                                                       | -             |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. Keep the default unless instructed by FlowX. | `CUSTOM`      |

***

### Logging configuration

| Environment Variable | Description                    | Default Value |
| -------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT` | Root logging level             | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-specific log level | `INFO`        |

***

## Secrets management

| Secret Name                                                            | Description                                   |
| ---------------------------------------------------------------------- | --------------------------------------------- |
| `SPRING_DATA_MONGODB_URI`                                              | MongoDB connection URI (contains credentials) |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret               |
| `FLOWX_SPICEDB_TOKEN`                                                  | SpiceDB authentication token                  |

***

## Ingress and CORS

The AI Gateway is exposed on the admin host because the Designer connects to it directly from the browser. Because it streams chat responses over SSE, the ingress must allow long-lived connections — the FlowX deploy chart raises the default proxy read/send timeouts for this service so streams are not cut mid-flight.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                      | Default Value |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Must include every Designer domain that uses AI chat. Supports wildcard subdomains (`https://*.yourcompany.com`). | `-`           |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults. For the complete route reference and Gateway API HTTPRoute configuration, see the [ingress configuration guide](./ingress-configuration).

***

## Deployment

### Helm values example

```yaml theme={"system"}
fullnameOverride: ai-gateway

image:
  repository: <your-registry>/ai-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # OAuth2
  SECURITY_TYPE: oauth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

  # CORS — origins that use the Designer AI chat
  APPLICATION_CORS_ALLOWORIGIN: https://designer.example.com

extraEnvVarsMultipleSecretsCustomKeys:
  - name: mongodb-generic
    secrets:
      SPRING_DATA_MONGODB_URI: mongodb-uri
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: true
  admin:
    enabled: true

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/routing-name: "ai-gateway"
  flowx.ai/prometheus-scrape: "ai-gateway"
```

<Info>
  The AI Gateway requires ingress to be enabled because the Designer connects to it from the browser to open AI chat streams.
</Info>

***

## Verify your setup

<Check>
  The AI Gateway pod is running and healthy: `kubectl get pods -l app=ai-gateway`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://ai-gateway:8080/actuator/health`
</Check>

<Check>
  SpiceDB connection is established — check pod logs for successful CAS client initialization
</Check>

<Check>
  AI chat opens in the Designer and streams a response without the connection dropping
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="AI chat stream drops mid-response">
    **Solutions:**

    1. Confirm the ingress proxy read/send timeouts are raised for the AI Gateway route (SSE needs long-lived connections)
    2. Check that no intermediate proxy buffers or closes the SSE stream
    3. Review pod logs for upstream errors from the config-time agents
  </Accordion>

  <Accordion title="AI chat returns a CORS error in the browser">
    **Solutions:**

    1. Add the Designer origin to `APPLICATION_CORS_ALLOWORIGIN`
    2. Verify the request reaches the AI Gateway on the admin host
  </Accordion>

  <Accordion title="SpiceDB connection failures">
    **Solutions:**

    1. Verify SpiceDB is running and reachable at the configured host and port
    2. Check that the SpiceDB token is correct
    3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="AI Platform setup" icon="hand-sparkles" href="../ai-platform/ai-platform-setup">
    Config-time agents and AI infrastructure
  </Card>

  <Card title="SpiceDB Configuration" icon="shield-halved" href="./spicedb">
    Fine-grained authorization setup
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>

  <Card title="Ingress configuration" icon="route" href="./ingress-configuration">
    Routing and CORS reference
  </Card>
</CardGroup>


# Audit setup
Source: https://docs.flowx.ai/5.9/setup-guides/audit-setup-guide

This guide will walk you through the process of setting up the Audit service and configuring it to meet your needs.

## Infrastructure prerequisites

The Audit service requires the following components to be set up before it can be started:

* **Docker engine**
* **Kafka**
* **Elasticsearch**

<Info>
  **Redis is not required.** audit-core does not depend on Redis. If you previously configured Redis for this service, those environment variables can be removed from your deployment.
</Info>

***

## Dependencies

The Audit service is built as a Docker image and runs on top of Kafka and Elasticsearch. Therefore, these services must be set up and running before starting the Audit service.

* [**Kafka configuration**](./setup-guides-overview#kafka)
* [**Authorization & access roles**](./setup-guides-overview#authorization--access-roles)
* [**Elasticsearch**](#configuring-elasticsearch)
* [**Logging**](./setup-guides-overview#logging)

***

## Configuration

### Configuring Kafka

To configure the Kafka server for the Audit service, set the following environment variables:

#### Connection settings

| Variable                  | Description                                                                          | Default Value      |
| ------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)                  | `localhost:9092`   |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT`        |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes)                                                         | `52428800` (50 MB) |

#### Consumer configuration

| Variable                           | Description                                 | Default Value |
| ---------------------------------- | ------------------------------------------- | ------------- |
| `SPRING_KAFKA_CONSUMER_GROUPID`    | Consumer group ID for audit logs            | `audit-gid`   |
| `KAFKA_CONSUMER_THREADS`           | Number of consumer threads                  | `1`           |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after auth failure (seconds) | `10`          |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Topic naming configuration

| Variable                         | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

#### Kafka topics

| Variable               | Description                    | Default Value                         |
| ---------------------- | ------------------------------ | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_IN` | Topic for receiving audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Configuring Elasticsearch

Configure Elasticsearch connection for audit data storage:

| Variable                                     | Description                                 | Default Value |
| -------------------------------------------- | ------------------------------------------- | ------------- |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL`         | Connection protocol                         | `https`       |
| `SPRING_ELASTICSEARCH_REST_URIS`             | URL(s) of Elasticsearch nodes (no protocol) | -             |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL`       | Disable SSL verification                    | `false`       |
| `SPRING_ELASTICSEARCH_REST_USERNAME`         | Authentication username                     | -             |
| `SPRING_ELASTICSEARCH_REST_PASSWORD`         | Authentication password                     | -             |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME`     | Audit data stream name                      | `audit-logs`  |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS`   | Number of primary shards                    | `2`           |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | Number of replica shards                    | `0`           |

<Info>
  The Elasticsearch index settings determine how your audit data is distributed and replicated across the cluster. The number of shards affects search performance and indexing, while replicas provide redundancy.
</Info>

### CAS lib configuration

| Environment Variable  | Description                  | Default Value |
| --------------------- | ---------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-`           |

### Configuring logging

To control the log levels, set the following environment variables:

| Variable             | Description                | Default Value |
| -------------------- | -------------------------- | ------------- |
| `LOGGING_LEVEL_ROOT` | Log level for root service | `INFO`        |
| `LOGGING_LEVEL_APP`  | Log level for application  | `INFO`        |

***

## Ingress and CORS

The Audit Core service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/audit`      | `/`              |

The path is set through `services.audit-core.ingress.admin.path` (or `services.audit-core.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                      | Default Value |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Audit Core. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Audit logs not appearing">
    **Symptoms:** Audit events are not being recorded or are missing from search results.

    **Solutions:**

    1. Verify the `KAFKA_TOPIC_AUDIT_IN` topic exists and matches the topic other services publish to (`ai.flowx.core.trigger.save.audit.v1`)
    2. Check that the consumer group ID (`SPRING_KAFKA_CONSUMER_GROUPID`) is correctly configured and not conflicting with another consumer
    3. Ensure Kafka connectivity by verifying `KAFKA_BOOTSTRAP_SERVERS` is reachable from the pod
    4. Check consumer thread count (`KAFKA_CONSUMER_THREADS`) — increase if throughput is insufficient
  </Accordion>

  <Accordion title="Elasticsearch connection errors">
    **Symptoms:** Service fails to start or throws connection errors related to Elasticsearch.

    **Solutions:**

    1. Verify `SPRING_ELASTICSEARCH_REST_URIS` points to a reachable Elasticsearch node (do not include the protocol in this value)
    2. Check that `SPRING_ELASTICSEARCH_REST_PROTOCOL` matches your Elasticsearch setup (`https` or `http`)
    3. If using SSL, ensure `SPRING_ELASTICSEARCH_REST_DISABLESSL` is set appropriately and certificates are valid
    4. Verify `SPRING_ELASTICSEARCH_REST_USERNAME` and `SPRING_ELASTICSEARCH_REST_PASSWORD` credentials are correct
  </Accordion>

  <Accordion title="High storage consumption">
    **Symptoms:** Elasticsearch disk usage grows rapidly or cluster health turns yellow/red.

    **Solutions:**

    1. Review your index lifecycle management (ILM) policies to ensure old audit data is rolled over and deleted on schedule
    2. Adjust `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` and `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` — fewer replicas reduce storage at the cost of redundancy
    3. Check the `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` data stream for excessive index count
    4. Consider reducing the retention period for audit logs in your ILM policy
  </Accordion>

  <Accordion title="Audit events delayed">
    **Symptoms:** Audit entries appear in Elasticsearch with significant delay after the triggering action.

    **Solutions:**

    1. Check Kafka consumer lag for the audit consumer group using your Kafka monitoring tools
    2. Increase `KAFKA_CONSUMER_THREADS` to allow parallel consumption if lag is consistently high
    3. Verify Elasticsearch cluster health — a degraded cluster slows down indexing
    4. Check `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` — frequent auth failures with long retry intervals can cause delays
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Audit Log" icon="clipboard-check" href="../docs/platform-deep-dive/core-extensions/audit">
    Learn about the audit logging system and how to view audit trails
  </Card>

  <Card title="Elasticsearch Indexing" icon="magnifying-glass" href="./flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing">
    Configure Elasticsearch indexing for process data
  </Card>
</CardGroup>


# FlowX CMS setup
Source: https://docs.flowx.ai/5.9/setup-guides/cms-setup

Set up the FlowX CMS Docker microservice for managing taxonomies and content inside an app.

Ensure the following infrastructure components are available before starting the CMS service:

* **MongoDB**
* **Redis**
* **Kafka**
* **Elasticsearch**

<Info>
  The service is pre-configured with most default values. However, some environment variables require customization during setup.
</Info>

## Dependencies overview

* [**MongoDB instance**](#mongodb-database)
* [**Authorization & access roles**](#configuring-authorization-access-roles)
* [**Redis**](#configuring-redis)
* [**Kafka**](#configuring-kafka)

***

## Configuration

### Set application defaults

Define the default application name for retrieving content:

```yaml theme={"system"}
application:
    defaultApplication: ${DEFAULT_APPLICATION:flowx}
```

<Info>
  If this configuration is not provided, the default value will be set to `flowx`.
</Info>

***

## Configuring authorization & access roles

The CMS validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| Environment variable                                      | Description                                                           | Default Value                    |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                 |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                  |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

***

## Configuring Runtime Manager service account

The CMS service requires access to the Runtime Manager service account for operations such as merging media file updates, managing builds, and handling application version transitions.

| Environment variable             | Description                                             | Default value              |
| -------------------------------- | ------------------------------------------------------- | -------------------------- |
| `APPLICATION_FLOWXRUNTIMESANAME` | Name of the Runtime Manager service account in Keycloak | `flowx-runtime-manager-sa` |

<Info>
  This service account is required for CMS to perform operations like merging media file updates and coordinating with the Runtime Manager service. The service account must exist in Keycloak with the appropriate roles assigned.
</Info>

***

## Configuring MongoDB

The CMS requires MongoDB for taxonomy and content storage. Configure MongoDB with the following variables:

| Environment variable         | Description                                                                                                                                      | Default value                                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `SPRING_DATA_MONGODB_URI`    | URI for connecting to the CMS MongoDB instance. The database name (`cms-core`) is fixed in the URI path; only the credentials are parameterized. | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/cms-core?retryWrites=false` |
| `DB_USERNAME`                | MongoDB username (shared by the CMS and runtime connections)                                                                                     | `paperflow`                                                                                                        |
| `DB_PASSWORD`                | MongoDB password (shared by the CMS and runtime connections)                                                                                     | `password`                                                                                                         |
| `MONGOCK_TRANSACTIONENABLED` | Enables transactions in MongoDB for Mongock library                                                                                              | `false` (Set to `false` to support successful migrations)                                                          |

<Info>
  Set `MONGOCK_TRANSACTIONENABLED` to `false` due to known issues with transactions in MongoDB version 5.
</Info>

### Configuring MongoDB (runtime database - additional data)

CMS also connects to a Runtime MongoDB instance for operational data. It reuses the same `DB_USERNAME` and `DB_PASSWORD` as the primary connection — there are no separate runtime credential variables:

| Environment variable                  | Description                                                                                                                              | Default value                                                                                                         |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable the Runtime MongoDB connection                                                                                                    | `true`                                                                                                                |
| `SPRING_DATA_MONGODB_RUNTIME_URI`     | URI for connecting to Runtime MongoDB. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/app-runtime?retryWrites=false` |
| `SPRING_DATA_MONGODB_STORAGE`         | Storage type for Runtime MongoDB (Azure environments only)                                                                               | `mongodb` (Options: `mongodb`, `cosmosdb`)                                                                            |

***

## Configuring Redis

CMS uses Redis for caching content. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

***

## Configuring Kafka

### Connection settings

| Environment variable             | Description                 | Default value    |
| -------------------------------- | --------------------------- | ---------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Address of the Kafka server | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka | `"PLAINTEXT"`    |

### Auth and retry configuration

| Environment variable               | Description                                     | Default value     |
| ---------------------------------- | ----------------------------------------------- | ----------------- |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after an authorization exception | `10`              |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size in bytes                   | `52428800` (50MB) |

### Consumer group configuration

| Environment variable                        | Description                            | Default value                    |
| ------------------------------------------- | -------------------------------------- | -------------------------------- |
| `KAFKA_CONSUMER_GROUPID_CONTENTTRANSLATE`   | Group ID for content translation       | `cms-consumer-group`             |
| `KAFKA_CONSUMER_GROUPID_RESUSAGEVALIDATION` | Group ID for resource usage validation | `cms-res-usage-validation-group` |

### Consumer thread configuration

| Environment variable                        | Description                           | Default value |
| ------------------------------------------- | ------------------------------------- | ------------- |
| `KAFKA_CONSUMER_THREADS_CONTENTTRANSLATE`   | Threads for content translation       | `1`           |
| `KAFKA_CONSUMER_THREADS_RESUSAGEVALIDATION` | Threads for resource usage validation | `2`           |

### Topic naming configuration

| Environment Variable                      | Description                         | Default Value     |
| ----------------------------------------- | ----------------------------------- | ----------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`              | Package prefix for topic names      | `ai.flowx.`       |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT`          | Environment segment for topic names | ` `               |
| `KAFKA_TOPIC_NAMING_VERSION`              | Version suffix for topic names      | `.v1`             |
| `KAFKA_TOPIC_NAMING_SEPARATOR`            | Primary separator for topic names   | `.`               |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`           | Secondary separator for topic names | `-`               |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern              | `engine.receive.` |

### Content request topics

| Environment variable              | Description                                   | Default value                                                    |
| --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- |
| `KAFKA_TOPIC_REQUEST_CONTENT_IN`  | Topic for incoming content retrieval requests | `ai.flowx.plugin.cms.trigger.retrieve.content.v1`                |
| `KAFKA_TOPIC_REQUEST_CONTENT_OUT` | Topic for content retrieval results           | `ai.flowx.engine.receive.plugin.cms.retrieve.content.results.v1` |

### Audit topics

| Environment variable    | Description                  | Default value                         |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Application resource usage validation

| Environment variable                            | Description                         | Default value                                                             |
| ----------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
| `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` | Topic for resource usage validation | `ai.flowx.application-version.resources-usages.sub-res-validation.cms.v1` |

<Tip>
  All actions that match a configured pattern will be consumed by the engine.
</Tip>

### Inter-Service topic coordination

When configuring Kafka topics in the FlowX ecosystem, it's critical to ensure proper coordination between services:

1. **Topic name matching**: Output topics from one service must match the expected input topics of another service.

   For example:

   * `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_CMS` on Application Manager must match `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` on CMS

2. **Pattern consistency**: The pattern values must be consistent across services:

   * Process Engine listens to topics matching: `ai.flowx.engine.receive.*`
   * Integration Designer listens to topics matching: `ai.flowx.integration.receive.*`

3. **Communication flow**:
   * Other services write to topics matching the Engine's pattern → Process Engine listens
   * Process Engine writes to topics matching the Integration Designer's pattern → Integration Designer listens

<Info>
  The exact pattern value isn't critical, but it must be identical across all connected services. Some deployments require manually creating Kafka topics in advance rather than dynamically. In these cases, all topic names must be explicitly defined and coordinated.
</Info>

### Kafka authentication

For secure environments, enable OAuth authentication with the following environment variables:

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

***

## CAS lib configuration

| Environment Variable  | Description                  | Default Value |
| --------------------- | ---------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-`           |

***

## Configuring logging

| Environment variable | Description                             |
| -------------------- | --------------------------------------- |
| `LOGGING_LEVEL_ROOT` | Log level for root service logs         |
| `LOGGING_LEVEL_APP`  | Log level for application-specific logs |

***

## Configuring file storage

### Public storage

| Environment variable                       | Description                                             |
| ------------------------------------------ | ------------------------------------------------------- |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`     | URL of S3 server for file storage                       |
| `APPLICATION_FILESTORAGE_S3_BUCKETNAME`    | S3 bucket name                                          |
| `APPLICATION_FILESTORAGE_S3_ROOTDIRECTORY` | Root directory in S3 bucket                             |
| `APPLICATION_FILESTORAGE_S3_CREATEBUCKET`  | Auto-create bucket if it doesn't exist (`true`/`false`) |
| `APPLICATION_FILESTORAGE_S3_PUBLICURL`     | Public URL for accessing files                          |

#### Private storage

Private CMS securely stores uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints.

<Info>
  Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from application builds.
</Info>

| Environment variable                             | Description                                 |
| ------------------------------------------------ | ------------------------------------------- |
| `APPLICATION_FILESTORAGE_S3_PRIVATESERVERURL`    | URL of S3 server for private storage        |
| `APPLICATION_FILESTORAGE_S3_PRIVATEBUCKETNAME`   | S3 bucket name for private storage          |
| `APPLICATION_FILESTORAGE_S3_PRIVATECREATEBUCKET` | Auto-create private bucket (`true`/`false`) |
| `APPLICATION_FILESTORAGE_S3_PRIVATEACCESSKEY`    | Access key for private S3 server            |
| `APPLICATION_FILESTORAGE_S3_PRIVATESECRETKEY`    | Secret key for private S3 server            |

***

## Configuring file upload size

| Environment variable                      | Description                      | Default value |
| ----------------------------------------- | -------------------------------- | ------------- |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE`    | Maximum file size for uploads    | `50MB`        |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size for uploads | `50MB`        |

<Warning>
  Setting high file size limits may increase vulnerability to potential attacks. Consider security implications before increasing these limits.
</Warning>

***

## Configuring application management

***

## Ingress and CORS

The CMS Core service is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/cms`        | `/`              |
| public     | `/cms`        | `/`              |

Paths are set through `services.cms-core.ingress.admin.path` / `services.cms-core.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                        | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls CMS. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="CMS service fails to start">
    **Symptoms:** Service crashes on startup or fails health checks.

    **Solutions:**

    1. Verify MongoDB connection URI is correct and the `cms-core` database is accessible
    2. Check that Kafka bootstrap servers are reachable and topic names are properly configured
    3. Ensure Redis is running and connection parameters are correct
    4. Review startup logs for specific error messages related to database migrations (`MONGOCK_TRANSACTIONENABLED` should be `false`)
  </Accordion>

  <Accordion title="Enumerations not syncing">
    **Symptoms:** Enumeration values are outdated or not appearing across services.

    **Solutions:**

    1. Verify Kafka topics for content translation are correctly configured (`KAFKA_TOPIC_REQUEST_CONTENT_IN` and `KAFKA_TOPIC_REQUEST_CONTENT_OUT`)
    2. Check that consumer group IDs are unique and not conflicting with other service instances
    3. Ensure Redis cache is not serving stale data — restart the CMS service to force cache invalidation
    4. Confirm the resource usage validation topic (`KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION`) is properly configured
  </Accordion>

  <Accordion title="Media library uploads failing">
    **Symptoms:** File uploads return errors or files are not visible in the Media Library.

    **Solutions:**

    1. Verify S3/MinIO server URL and bucket configuration (`APPLICATION_FILESTORAGE_S3_SERVERURL`, `APPLICATION_FILESTORAGE_S3_BUCKETNAME`)
    2. Check that the bucket exists or `APPLICATION_FILESTORAGE_S3_CREATEBUCKET` is set to `true`
    3. Ensure file size limits are appropriate (`SPRING_SERVLET_MULTIPART_MAXFILESIZE` and `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`)
    4. For private storage, verify access key and secret key credentials are correct
  </Accordion>

  <Accordion title="Content not appearing in Designer">
    **Symptoms:** CMS content (enumerations, media files) is not visible in the FlowX Designer.

    **Solutions:**

    1. Verify CMS service is running and healthy by checking the `/actuator/health` endpoint
    2. Ensure the CMS service is reachable from the Designer — check network policies and ingress configuration
    3. Verify CORS settings allow requests from the Designer domain
    4. Check that the authorization configuration is correct and the Designer can authenticate with the CMS service
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Enumerations" icon="list" href="../docs/platform-deep-dive/core-extensions/content-management/enumerations">
    Manage taxonomies and enumeration values for your applications
  </Card>

  <Card title="Media Library" icon="photo-film" href="../docs/platform-deep-dive/core-extensions/content-management/media-library">
    Store and manage media assets used across your applications
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>
</CardGroup>


# Data-Sync job setup
Source: https://docs.flowx.ai/5.9/setup-guides/data-sync

Comprehensive guide for configuring and deploying the Data-Sync Job in your Kubernetes environment

## Overview

The Data-Sync Job synchronizes data across multiple databases to maintain consistency and up-to-date information throughout your system. It operates by connecting to various databases, retrieving data, and synchronizing changes across them. The job logs all actions and can be scheduled to run at regular intervals.

***

## Quick start

```bash theme={"system"}
# 1. Configure your environment variables in a data-sync-job.yaml file
# 2. Apply the configuration
kubectl apply -f data-sync-job.yaml
# 3. Monitor the job status
kubectl get jobs
# 4. Check logs if needed
kubectl logs job/data-sync-job
```

***

## Required environment variables

<Warning>
  The Data-Sync Job synchronizes **all core platform components** and requires a database connection for each of them, including the Documents and Notifications plugins. All core platform components must be installed — skipping services during synchronization is not supported, and the job does not start if a connection is missing.
</Warning>

### Database connections

The Data-Sync Job requires connection details for multiple databases. Configure the following sections based on your deployment.

#### MongoDB connections

Each MongoDB-based service requires the following variables:

| Component                | Required Variables                                                                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **CMS**                  | `FLOWX_DATASOURCE_CMS_URI`, `CMS_MONGO_USERNAME`, `CMS_MONGO_PASSWORD`, `CMS_MONGO_DATABASE`                                                                 |
| **Scheduler**            | `FLOWX_DATASOURCE_SCHEDULER_URI`, `SCHEDULER_MONGO_USERNAME`, `SCHEDULER_MONGO_PASSWORD`, `SCHEDULER_MONGO_DATABASE`                                         |
| **Task Manager**         | `FLOWX_DATASOURCE_TASKMANAGER_URI`, `TASKMANAGER_MONGO_USERNAME`, `TASKMANAGER_MONGO_PASSWORD`, `TASKMANAGER_MONGO_DATABASE`                                 |
| **Document Plugin**      | `FLOWX_DATASOURCE_DOCUMENTPLUGIN_URI`, `DOCUMENTPLUGIN_MONGO_USERNAME`, `DOCUMENTPLUGIN_MONGO_PASSWORD`, `DOCUMENTPLUGIN_MONGO_DATABASE`                     |
| **Notification Plugin**  | `FLOWX_DATASOURCE_NOTIFICATIONPLUGIN_URI`, `NOTIFICATIONPLUGIN_MONGO_USERNAME`, `NOTIFICATIONPLUGIN_MONGO_PASSWORD`, `NOTIFICATIONPLUGIN_MONGO_DATABASE`     |
| **App Runtime**          | `FLOWX_DATASOURCE_APPRUNTIME_URI`, `APPRUNTIME_MONGO_USERNAME`, `APPRUNTIME_MONGO_PASSWORD`, `APPRUNTIME_MONGO_DATABASE`                                     |
| **Integration Designer** | `FLOWX_DATASOURCE_INTEGRATIONDESIGNER_URI`, `INTEGRATIONDESIGNER_MONGO_USERNAME`, `INTEGRATIONDESIGNER_MONGO_PASSWORD`, `INTEGRATIONDESIGNER_MONGO_DATABASE` |
| **Admin**                | `FLOWX_DATASOURCE_ADMIN_URI`, `ADMIN_MONGO_USERNAME`, `ADMIN_MONGO_PASSWORD`, `ADMIN_MONGO_DATABASE`                                                         |

##### MongoDB URI format

```
mongodb://${USERNAME}:${PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/${DATABASE}
```

#### PostgreSQL connections

| Component                 | Required Variables                                                                                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Process Engine**        | `FLOWX_DATASOURCE_ENGINE_URL`, `FLOWX_DATASOURCE_ENGINE_USERNAME`, `FLOWX_DATASOURCE_ENGINE_PASSWORD`, `FLOWX_DATASOURCE_ENGINE_DRIVERCLASSNAME`                 |
| **Application Manager**   | `FLOWX_DATASOURCE_APPMANAGER_URL`, `FLOWX_DATASOURCE_APPMANAGER_USERNAME`, `FLOWX_DATASOURCE_APPMANAGER_PASSWORD`, `FLOWX_DATASOURCE_APPMANAGER_DRIVERCLASSNAME` |
| **Authentication System** | `FLOWX_DATASOURCE_AUTHSYSTEM_URL`, `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME`, `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD`                                                |
| **Organization Manager**  | `FLOWX_DATASOURCE_ORGMANAGER_URL`, `FLOWX_DATASOURCE_ORGMANAGER_USERNAME`, `FLOWX_DATASOURCE_ORGMANAGER_PASSWORD`, `FLOWX_DATASOURCE_ORGMANAGER_DRIVERCLASSNAME` |
|                           |                                                                                                                                                                  |

### OpenID provider configuration

Starting with 5.9.0, data-sync provisions FlowX-managed end-user groups and runtime roles in Keycloak as part of the [runtime authorization](./access-management/runtime-authorization) rollout. Provide admin credentials so the job can call the Keycloak admin API.

| Environment Variable     | Description                                                                                                   | Default Value |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_OPENID_PROVIDER`  | OpenID provider type. Set to `keycloak` (the only supported provider).                                        | `-`           |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path (for example, `https://auth.example.com/auth/`). | `-`           |
| `FLOWX_OPENID_USER`      | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm.                     | `-`           |
| `FLOWX_OPENID_PASSWORD`  | Password for the admin account above. Store in a Kubernetes Secret.                                           | `-`           |
| `FLOWX_OPENID_CLIENTID`  | Keycloak admin client used to obtain the admin token.                                                         | `admin-cli`   |

##### Driver class names

* PostgreSQL: `org.postgresql.Driver`
* Oracle: `oracle.jdbc.OracleDriver`

### Additional configuration

| Variable                                        | Description                                                 |
| ----------------------------------------------- | ----------------------------------------------------------- |
| `SPRING_JPA_DATABASE`                           | Database type for Spring JPA (e.g., `postgresql`, `oracle`) |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULTSCHEMA` | Default schema for Hibernate                                |
| `LOGGING_CONFIG_FILE`                           | Path to logging configuration file                          |

***

## Service to database mapping

Each service in your environment corresponds to specific database datasources:

| Service                  | Datasources              |
| ------------------------ | ------------------------ |
| `scheduler-core`         | scheduler                |
| `cms-core`               | cms                      |
| `task-management-plugin` | task-manager             |
| `document-plugin`        | document-plugin          |
| `notification-plugin`    | notification-plugin      |
| `runtime-manager`        | app-runtime, app-manager |
| `integration-designer`   | integration-designer     |
| `admin`                  | admin, engine            |
| `process-engine`         | engine                   |
| `application-manager`    | app-manager              |
| `authorization-system`   | auth-system              |

***

## Sample configuration

```yaml theme={"system"}
apiVersion: batch/v1
kind: Job
metadata:
  name: data-sync-job
spec:
  template:
    spec:
      containers:
      - name: data-sync
        image: your-registry/data-sync:latest
        env:
        # MongoDB connections
        - name: FLOWX_DATASOURCE_CMS_URI
          value: "mongodb://${CMS_MONGO_USERNAME}:${CMS_MONGO_PASSWORD}@mongodb-0.mongodb-headless:27017/${CMS_MONGO_DATABASE}"
        # Add all other required environment variables
      restartPolicy: Never
  backoffLimit: 3
```

***

## SpiceDB configuration

| Environment Variable  | Description                  | Default Value |
| --------------------- | ---------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-`           |

***

## Best practices

1. Store sensitive credentials in Kubernetes Secrets and reference them in your deployment
2. Include the Data-Sync Job in your CI/CD pipeline for automated deployment
3. Schedule regular runs using a Kubernetes CronJob for periodic synchronization
4. Monitor job execution and set up alerts for failures

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** The Data-Sync Job fails to start or exits with database connection errors.

    **Solutions:**

    1. Verify MongoDB and PostgreSQL connection strings are correctly formatted
    2. Check that database credentials are correct and the user has appropriate permissions
    3. Ensure network connectivity between the job pod and database services
    4. For MongoDB, confirm the replica set is healthy and reachable
    5. For PostgreSQL, verify the JDBC URL format and driver class name
  </Accordion>

  <Accordion title="Sync failures">
    **Symptoms:** Data synchronization completes partially or fails.

    **Note:** The Data-Sync Job does **not** use Kafka. It is a batch job that connects directly to each service's database to synchronize data.

    **Solutions:**

    1. Check job logs for specific error messages: `kubectl logs job/data-sync-job`
    2. Verify all database connection strings are correct and reachable from the job pod
    3. Ensure database users have the required read/write permissions
    4. Confirm that all core platform components are installed and their connection variables are set
  </Accordion>

  <Accordion title="Data inconsistencies after sync">
    **Symptoms:** Data across services appears out of date or mismatched after the job completes.

    **Solutions:**

    1. Check the service-to-database mapping to ensure each service points to the right datasource
    2. Re-run the Data-Sync Job and monitor logs for partial failures
    3. Confirm that no concurrent writes occurred during the sync window
  </Accordion>

  <Accordion title="Missing required variables">
    **Symptoms:** Job fails immediately on startup with configuration errors.

    **Solutions:**

    1. Ensure all required environment variables are set for each database connection
    2. Check for typos in environment variable names
    3. Set the connection variables for every core platform component — the job requires all of them, including components your processes may not actively use
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Document Parser setup
Source: https://docs.flowx.ai/5.9/setup-guides/document-parser-setup

Configure the Document Parser service for document text extraction, OCR processing, and AI-powered document parsing.

The Document Parser service handles document and image processing for AI workflows. It provides multiple parsing engines, OCR capabilities, table extraction, document classification, and signature detection.

## Dependencies

The Document Parser connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — async document processing and inter-service communication
* [**Identity provider**](/5.9/setup-guides/access-management/configuring-an-iam-solution) (Keycloak or Azure AD) — authentication
* [**CMS Core**](/5.9/setup-guides/cms-setup) — file retrieval from FlowX content management
* **AI provider** (OpenAI, Azure OpenAI, Ollama, Anthropic, or GCP) — required for LLM and VLM parsing engines
* **Vector database** (Qdrant or PostgreSQL with pgvector) — optional, for RAG use cases

<Info>
  The Document Parser retrieves files through CMS Core — it does not require its own S3/MinIO storage configuration.
</Info>

<Info>
  The Document Parser is a Python 3.13 service that loads ML models at startup. Plan for longer startup times (5–20 minutes) compared to Java-based FlowX services.
</Info>

***

## Capabilities

### What it can do

* **Multi-format parsing**: PDF, DOCX, XLSX/XLS/XLSM, PPTX, JPG, PNG, TIFF
* **Three parsing engine families**: Classic, LLM, and Docling (with Auto/Simple/OCR/VLM modes)
* **OCR text extraction**: Tesseract, RapidOCR, EasyOCR
* **Table structure extraction**: Detect and extract tabular data
* **Document classification**: Keyword-based or LLM-based
* **Signature detection**: Locate signatures within documents
* **Page rotation detection**: Detect and correct rotated pages
* **Semantic chunking**: Smart chunking for Retrieval-Augmented Generation (RAG) workflows
* **Vector store integration**: Store embeddings in Qdrant or PostgreSQL/pgvector

### What it cannot do

* Cannot process encrypted or password-protected PDFs
* Cannot process audio or video files
* Cannot edit or modify source documents
* Does not perform language translation

***

## Supported formats

| Format     | Extensions               | Notes                           |
| ---------- | ------------------------ | ------------------------------- |
| PDF        | `.pdf`                   | All parsing engines supported   |
| Word       | `.docx`                  | Docling and Classic engines     |
| Excel      | `.xlsx`, `.xls`, `.xlsm` | Table extraction supported      |
| PowerPoint | `.pptx`                  | Slide-by-slide extraction       |
| Images     | `.jpg`, `.png`, `.tiff`  | Converted to PDF before parsing |

***

## Parsing engines

The Document Parser supports six parsing modes organized into three engine families:

| Engine         | API Value             | Best for                        | Speed  | Cost        | Accuracy   |
| -------------- | --------------------- | ------------------------------- | ------ | ----------- | ---------- |
| Classic        | `ClassicParser`       | Clean text PDFs                 | Fast   | Free        | Low–Medium |
| LLM            | `LLMParser`           | Any document via AI vision      | Slow   | High        | High       |
| Docling Simple | `DoclingParserSimple` | Standard business documents     | Medium | Low         | Medium     |
| Docling OCR    | `DoclingParserOCR`    | Scanned/image-heavy documents   | Slow   | Medium–High | High       |
| Docling VLM    | `DoclingParserVLM`    | Complex layouts                 | Slow   | High        | Highest    |
| Docling Auto   | `DoclingParserAuto`   | Unknown documents (auto-routes) | Varies | Varies      | Varies     |

<Info>
  **Docling Auto** analyzes each page using text density, gibberish ratio, image area coverage, and layout metrics. It then routes each page to the cheapest engine that can handle it: **Standard** (simple extraction), **OCR** (text-poor/garbled pages), or **VLM** (complex visual layouts).
</Info>

### Engine selection guide

<Tabs>
  <Tab title="Classic">
    Uses PyMuPDF for direct text extraction from the PDF file structure, with Tesseract OCR as a fallback for empty pages.

    * Zero cost (no external API calls)
    * Fastest processing
    * Only works with digital PDFs that have selectable text
    * Falls back to Tesseract OCR when pages have no text layer
  </Tab>

  <Tab title="LLM">
    Encodes each page as a base64 image and sends it to an AI vision model for extraction.

    * Highest accuracy for complex documents
    * Most expensive (AI API call per page)
    * Handles any document type including handwritten text
    * Supports multiple providers: OpenAI, Azure OpenAI, Ollama, Anthropic, GCP
  </Tab>

  <Tab title="Docling">
    IBM's open-source document processing library with multiple modes:

    * **Simple** — Layout analysis without OCR, good for standard business documents
    * **OCR** — Adds OCR processing for scanned documents
    * **VLM** — Uses vision-language models for the highest accuracy on complex layouts
    * **Auto** — Automatically selects the best mode per page based on content analysis
  </Tab>
</Tabs>

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/doc-parser`).

| Endpoint                                  | Method | Purpose                                                 |
| ----------------------------------------- | ------ | ------------------------------------------------------- |
| `/api/v1/doc-parser/extract/parse_file`   | POST   | Parse an uploaded file (multipart form)                 |
| `/api/v1/doc-parser/extract/parse_object` | POST   | Parse a file from CMS or MinIO (JSON body)              |
| `/api/v1/doc-parser/extract/store_text`   | POST   | Store extracted text as embeddings in a vector database |
| `/api/v1/doc-parser/info/health`          | GET    | Health check                                            |

***

## Configuration

### Server configuration

| Environment Variable        | Description                                 | Default Value |
| --------------------------- | ------------------------------------------- | ------------- |
| `URL_PREFIX`                | FastAPI root path for reverse proxy routing | `/doc-parser` |
| `GUNICORN_WORKERS`          | Number of Gunicorn worker processes         | `1`           |
| `GUNICORN_TIMEOUT`          | Worker timeout in seconds                   | `600`         |
| `GUNICORN_GRACEFUL_TIMEOUT` | Graceful shutdown timeout in seconds        | `320`         |
| `USE_DOCLING`               | Pre-download Docling models at startup      | `0`           |
| `VERBOSE`                   | Enable verbose/debug logging                | `0`           |

<Warning>
  Keep `GUNICORN_WORKERS` at `1` per pod. The Document Parser loads large ML models into memory — multiple workers per pod will cause out-of-memory (OOM) errors. Scale horizontally by adding more pods instead.
</Warning>

<Tip>
  Set `USE_DOCLING` to `1` if you use Docling parsing engines. This pre-downloads models at startup rather than on first request, avoiding timeout issues on the first document.
</Tip>

***

### AI model configuration

The Document Parser uses three types of AI models, each independently configurable:

| Model type | Variable               | Purpose                                                  | Default  |
| ---------- | ---------------------- | -------------------------------------------------------- | -------- |
| Chat       | `MODEL_TYPE`           | LLM-based parsing, classification, structured extraction | `OPENAI` |
| Vision     | `VISION_MODEL_TYPE`    | VLM parsing, image analysis                              | `OPENAI` |
| Embedding  | `EMBEDDING_MODEL_TYPE` | Vector store embeddings, semantic chunking               | `OPENAI` |

| Environment Variable       | Description                            | Default Value |
| -------------------------- | -------------------------------------- | ------------- |
| `FALLBACK_MODEL_TYPE`      | Fallback LLM provider if primary fails | -             |
| `STRUCTURED_OUTPUT_METHOD` | Structured output method for LLM       | `json_schema` |
| `VLM_API_TIMEOUT`          | Timeout in seconds for VLM API calls   | `300`         |

<Info>
  All three model types support the same providers: `OPENAI`, `AZUREOPENAI`, `OLLAMA`, `ANTHROPIC`, `GCP`, `GCP_VERTEX`, `CUSTOM_OPENAI`, `OPENAI_COMPATIBLE`. Embedding models additionally support `HUGGINGFACE` and `AWS`.
</Info>

#### Provider-specific variables

<Tabs>
  <Tab title="OpenAI">
    | Environment Variable          | Description          | Default Value            |
    | ----------------------------- | -------------------- | ------------------------ |
    | `OPENAI_API_KEY`              | OpenAI API key       | -                        |
    | `OPENAI_MODEL_NAME`           | Chat model name      | `gpt-5.4-mini`           |
    | `OPENAI_VISION_MODEL_NAME`    | Vision model name    | `gpt-5.4-mini`           |
    | `OPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |
    | `OPENAI_CHUNK_SIZE`           | Embedding chunk size | `1000`                   |
  </Tab>

  <Tab title="Azure OpenAI">
    | Environment Variable               | Description                 | Default Value            |
    | ---------------------------------- | --------------------------- | ------------------------ |
    | `AZURE_OPENAI_API_KEY`             | Azure OpenAI API key        | -                        |
    | `AZURE_OPENAI_INSTANCE_NAME`       | Azure OpenAI instance name  | -                        |
    | `AZURE_OPENAI_API_VERSION`         | Azure OpenAI API version    | `2025-01-01-preview`     |
    | `AZURE_OPENAI_MODEL`               | Azure model deployment name | `gpt-5.4-mini`           |
    | `AZUREOPENAI_MODEL_NAME`           | Chat model name             | `gpt-5.4-mini`           |
    | `AZUREOPENAI_VISION_MODEL_NAME`    | Vision model name           | `gpt-5.4-mini`           |
    | `AZUREOPENAI_EMBEDDING_MODEL_NAME` | Embedding model name        | `text-embedding-3-large` |
  </Tab>

  <Tab title="Ollama">
    | Environment Variable          | Description          | Default Value     |
    | ----------------------------- | -------------------- | ----------------- |
    | `OLLAMA_BASE_URL`             | Ollama server URL    | -                 |
    | `OLLAMA_MODEL_NAME`           | Chat model name      | `llama3.2:latest` |
    | `OLLAMA_VISION_MODEL_NAME`    | Vision model name    | `llava:7b-v1.6`   |
    | `OLLAMA_EMBEDDING_MODEL_NAME` | Embedding model name | `all-minilm:33m`  |
  </Tab>

  <Tab title="Other providers">
    **Anthropic:**

    | Environment Variable          | Description       | Default Value   |
    | ----------------------------- | ----------------- | --------------- |
    | `ANTHROPIC_MODEL_NAME`        | Chat model name   | `anthropic-1.0` |
    | `ANTHROPIC_VISION_MODEL_NAME` | Vision model name | `anthropic-1.0` |

    **Google Cloud / Vertex AI:**

    | Environment Variable    | Description             | Default Value    |
    | ----------------------- | ----------------------- | ---------------- |
    | `GCP_PROJECT_ID`        | Google Cloud project ID | -                |
    | `GCP_LOCATION`          | Google Cloud region     | -                |
    | `GCP_MODEL_NAME`        | Chat model name         | `gemini-1.5-pro` |
    | `GCP_VISION_MODEL_NAME` | Vision model name       | `gemini-1.5-pro` |

    **Custom OpenAI-compatible:**

    | Environment Variable                 | Description          | Default Value            |
    | ------------------------------------ | -------------------- | ------------------------ |
    | `CUSTOM_OPENAI_BASE_URL`             | API base URL         | -                        |
    | `CUSTOM_OPENAI_CLIENT_ID`            | Client ID            | -                        |
    | `CUSTOM_OPENAI_SECRET_KEY`           | Secret key           | -                        |
    | `CUSTOM_OPENAI_MODEL_NAME`           | Chat model name      | `gpt-5.4-mini`           |
    | `CUSTOM_OPENAI_VISION_MODEL_NAME`    | Vision model name    | `gpt-5.4-mini`           |
    | `CUSTOM_OPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |
  </Tab>
</Tabs>

***

### OCR configuration

| Environment Variable | Description                          | Default Value |
| -------------------- | ------------------------------------ | ------------- |
| `OMP_NUM_THREADS`    | Number of threads for OCR processing | `4`           |

<Info>
  The OCR engine is selected per-request via the API `ocr_engine` parameter. Available engines: `tesseract-cli` (default), `tesseract-ocr`, `rapidocr`, `easyocr`.
</Info>

***

### Vector database configuration (optional)

Required only if using semantic chunking and RAG workflows. The vector store provider is selected per-request via the API `vector_store_provider` parameter.

<Tabs>
  <Tab title="Qdrant">
    | Environment Variable | Description       | Default Value           |
    | -------------------- | ----------------- | ----------------------- |
    | `QDRANT_HOST`        | Qdrant server URL | `http://localhost:6333` |
  </Tab>

  <Tab title="PostgreSQL / pgvector">
    | Environment Variable | Description       | Default Value |
    | -------------------- | ----------------- | ------------- |
    | `POSTGRES_HOST`      | PostgreSQL host   | `localhost`   |
    | `POSTGRES_PORT`      | PostgreSQL port   | `5432`        |
    | `POSTGRES_DB`        | Database name     | `dip`         |
    | `POSTGRES_USER`      | Database username | -             |
    | `POSTGRES_PASSWORD`  | Database password | -             |
  </Tab>
</Tabs>

***

### Observability (optional)

#### Langfuse

| Environment Variable  | Description         | Default Value |
| --------------------- | ------------------- | ------------- |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | -             |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key | -             |
| `LANGFUSE_HOST`       | Langfuse server URL | -             |

***

## Deployment and sizing

### Kubernetes configuration (15,000 pages/day)

<Tabs>
  <Tab title="Steady load">
    For predictable, consistent workloads:

    | Setting            | Value   |
    | ------------------ | ------- |
    | Replicas           | 3       |
    | CPU requests       | 3 cores |
    | CPU limits         | 4 cores |
    | RAM requests       | 4 Gi    |
    | RAM limits         | 6 Gi    |
    | `GUNICORN_WORKERS` | `1`     |
    | `OMP_NUM_THREADS`  | `4`     |
  </Tab>

  <Tab title="Autoscaling">
    For variable workloads with burst capacity:

    | Setting            | Value   |
    | ------------------ | ------- |
    | Min replicas       | 2       |
    | Max replicas       | 7       |
    | CPU requests       | 3 cores |
    | CPU limits         | 4 cores |
    | RAM requests       | 4 Gi    |
    | RAM limits         | 6 Gi    |
    | `GUNICORN_WORKERS` | `1`     |
    | `OMP_NUM_THREADS`  | `4`     |
    | HPA target CPU     | 70%     |
  </Tab>
</Tabs>

### Important deployment notes

<Warning>
  **Pod startup time:** 5–20 minutes. The service loads ML models (OCR, Docling) into memory at startup. Configure your readiness probes and deployment strategy accordingly.
</Warning>

* Set `GUNICORN_TIMEOUT` to at least `600` (10 minutes) — increase for very large documents
* Use `1` Gunicorn worker per pod — scale horizontally with more pods
* Configure liveness probes with a generous initial delay (at least 300 seconds)
* Consider using a `RollingUpdate` strategy with `maxUnavailable: 0` to avoid downtime during deploys
* The service listens on port `8080`

***

## Cost considerations

Estimated monthly costs for a 15,000 pages/day workload using LLM-based parsing:

| Component                   | Monthly cost estimate |
| --------------------------- | --------------------- |
| OpenAI API calls            | \~\$960               |
| Kubernetes compute (3 pods) | \~\$150–500           |
| **Total**                   | **\~\$1,100–1,460**   |

### Cost reduction tips

<CardGroup>
  <Card title="Use keyword-only classification" icon="tag">
    Set `use_llm_to_classify` to `false` in API calls instead of LLM-based classification. Saves \~\$450/month.
  </Card>

  <Card title="Use Docling Auto" icon="wand-magic-sparkles">
    Let Docling Auto route pages to the cheapest engine that works. Saves \~\$240/month compared to forcing OCR on all pages.
  </Card>

  <Card title="Turn off signature detection" icon="toggle-off">
    Set `detect_signature` to `false` in API calls when not needed. Saves \~\$90/month.
  </Card>

  <Card title="Use Classic for clean PDFs" icon="bolt">
    Route clean digital PDFs to the Classic engine (free, no API calls). Reserve LLM/Docling for scanned or complex documents.
  </Card>
</CardGroup>

***

## Verify your setup

<Check>
  The Document Parser pod is running: `kubectl get pods -l app=document-parser`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://document-parser:8080/api/v1/doc-parser/info/health`
</Check>

<Check>
  ML models loaded successfully — check pod logs for model initialization messages (this can take 5–20 minutes)
</Check>

<Check>
  Test a document parse request against the `/api/v1/doc-parser/extract/parse_file` endpoint and verify the response contains extracted text
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="OOM kills (out of memory)">
    **Symptoms:** Pods restart with OOMKilled status.

    **Solutions:**

    * Increase memory limits (try 8 Gi)
    * Ensure `GUNICORN_WORKERS` is set to `1`
    * Reduce `OMP_NUM_THREADS` to `2`
    * Check for concurrent large document processing
  </Accordion>

  <Accordion title="Slow document processing">
    **Symptoms:** Documents take much longer than expected to process.

    **Solutions:**

    * Check if GPU is available for Docling VLM mode
    * Verify network latency to the AI provider
    * Use Docling Auto instead of forcing VLM on all documents
    * Check pod CPU utilization — may need more replicas
  </Accordion>

  <Accordion title="Low extraction accuracy">
    **Symptoms:** Extracted text is incomplete or garbled.

    **Solutions:**

    * Try VLM or LLM mode for complex documents
    * Check source document quality (low resolution images reduce OCR accuracy)
    * Ensure the correct OCR engine is configured for your document language
    * Use `apply_rotation: true` for scanned documents that may be rotated
  </Accordion>

  <Accordion title="Pod fails to start">
    **Symptoms:** Pod stays in CrashLoopBackOff or never becomes ready.

    **Solutions:**

    * Increase readiness probe initial delay to 600 seconds
    * Check that ML model files are accessible (network or storage issues)
    * Verify memory limits are sufficient for model loading (minimum 4 Gi)
    * Review pod logs for specific error messages
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Extract Data from File" icon="file-lines" href="/5.9/ai-platform/agent-builder/extract-data-from-file">
    Configure the Extract Data from File AI node in Agent Builder
  </Card>

  <Card title="AI Platform setup" icon="server" href="/5.9/ai-platform/ai-platform-setup">
    Configure AI Platform services and service discovery
  </Card>

  <Card title="Agent Builder overview" icon="robot" href="/5.9/ai-platform/agent-builder/overview">
    Get started with Agent Builder workflows
  </Card>
</CardGroup>


# Documents plugin setup
Source: https://docs.flowx.ai/5.9/setup-guides/documents-plugin-setup

The Documents plugin provides functionality for generating, persisting, combining, and manipulating documents within the FlowX.AI system.

The plugin is available as a docker image.

## Dependencies

Before setting up the plugin, ensure that you have the following dependencies installed and configured:

* [PostgreSQL](https://www.postgresql.org/) Database: You will need a PostgreSQL database to store data related to document templates and documents.
* [MongoDB](https://www.mongodb.com/2) Database: MongoDB is required for the HTML templates feature of the plugin.
* Kafka: Establish a connection to the Kafka instance used by the FlowX.AI engine.
* [Redis](https://redis.io/): Set up a Redis instance for caching purposes.
* S3-Compatible File Storage Solution: Deploy an S3-compatible file storage solution to store document files.

***

## Configuration

The plugin comes with pre-filled configuration properties, but you need to set up a few custom environment variables to tailor it to your specific setup. Here are the key configuration steps:

### Redis server

The plugin can utilize the [Redis component](https://app.gitbook.com/@flowx-ai/s/flowx-docs/flowx-engine/setup-guide#2-redis-server) already deployed for the FLOWX.AI engine. Make sure it is configured properly.

### Authorization configuration

The Documents plugin validates incoming tokens with the JWT public key mechanism:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                          |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                       |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`       |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                        |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### Document processing configuration

| Environment Variable                | Description                             | Default Value                                               |
| ----------------------------------- | --------------------------------------- | ----------------------------------------------------------- |
| `FLOWX_DEFAULTCLIENTTYPE`           | Default client type                     | `PF`                                                        |
| `FLOWX_HTML_TEMPLATES_ENABLED`      | Enable HTML templates feature           | `false`                                                     |
| `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` | Paths to fonts for HTML templates       | `/statics/fonts/Calibri.ttf, /statics/fonts/DejaVuSans.ttf` |
| `FLOWX_CONVERT_DPI`                 | DPI setting for PDF to image conversion | `150`                                                       |

<Info>
  Set the `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` config to select the font used for generating documents based on PDF templates.
</Info>

<Info>
  If you want to use specific fonts in your PDF templates, override the `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` config. By default, Calibri and DejaVuSans are available fonts.
</Info>

<Info>
  `FLOWX_CONVERT_DPI`:	Sets the DPI (dots per inch) for PDF to JPEG conversion. Higher values result in higher resolution images. (Default value: `150`).
</Info>

After making these configurations, the fonts will be available for use within PDF templates.

### Database configuration

#### SQL database (PostgreSQL)

The Documents Plugin uses a PostgreSQL database for relational data storage.

| Environment Variable                | Description                        | Default Value                                   |
| ----------------------------------- | ---------------------------------- | ----------------------------------------------- |
| `SPRING_DATASOURCE_URL`             | JDBC connection URL for PostgreSQL | `jdbc:postgresql://jx-documentdb:5432/document` |
| `SPRING_DATASOURCE_USERNAME`        | Database username                  | `postgres`                                      |
| `SPRING_DATASOURCE_PASSWORD`        | Database password                  | -                                               |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class                  | `org.postgresql.Driver`                         |

#### Primary MongoDB configuration

| Environment Variable                      | Description                | Default Value                                                 |
| ----------------------------------------- | -------------------------- | ------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI`                 | MongoDB connection URI     | `mongodb://flowx:password@jx-document-mongodb:27017/document` |
| `MONGODB_USERNAME`                        | MongoDB username           | `flowx`                                                       |
| `MONGODB_PASSWORD`                        | MongoDB password           | `password`                                                    |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | UUID representation format | `standard`                                                    |
| `SPRING_DATA_MONGODB_STORAGE`             | MongoDB storage type       | `mongodb`                                                     |

#### Runtime MongoDB configuration

| Environment Variable                              | Description                                                                                                                                           | Default Value                                                                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED`             | Enable runtime MongoDB connection                                                                                                                     | `true`                                                                                                              |
| `SPRING_DATA_MONGODB_RUNTIME_URI`                 | Runtime MongoDB connection URI                                                                                                                        | `mongodb://${DB_USERNAME:paperflow}:${DB_PASSWORD:password}@jx-app-runtime-mdb:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME`                                     | Runtime MongoDB username, referenced as a placeholder by the default URI. Optional — if you override the full URI, set the credentials there instead. | `paperflow`                                                                                                         |
| `DB_PASSWORD`                                     | Runtime MongoDB password, referenced as a placeholder by the default URI. Optional — see `DB_USERNAME`.                                               | `password`                                                                                                          |
| `SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION`   | Enable automatic index creation                                                                                                                       | `false`                                                                                                             |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | UUID representation format for runtime connection                                                                                                     | `standard`                                                                                                          |

### Redis configuration

Document Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

### Multipart upload configuration

| Environment Variable                      | Description                                | Default Value |
| ----------------------------------------- | ------------------------------------------ | ------------- |
| `SPRING_SERVLET_CONTEXTPATH`              | Servlet context path                       | `/`           |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE`    | Maximum file size for uploads              | `50MB`        |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size for multipart uploads | `50MB`        |

***

## Basic Kafka configuration

| Environment Variable               | Description                                                                 | Default Value                 |
| ---------------------------------- | --------------------------------------------------------------------------- | ----------------------------- |
| `KAFKA_BOOTSTRAP_SERVERS`          | Address of Kafka server(s) (also accepts `SPRING_KAFKA_BOOTSTRAPSERVERS`)   | `localhost:9092`              |
| `KAFKA_SECURITY_PROTOCOL`          | Security protocol for Kafka (also accepts `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT`                   |
| `SPRING_KAFKA_CONSUMER_GROUPID`    | Consumer group ID for the service                                           | `kafka-svc-document-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size in bytes                                               | `52428800` (50MB)             |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions                                          | `10` (seconds)                |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

***

## Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |

***

## Thread configuration

| Environment Variable                                                                          | Description                          | Default Value |
| --------------------------------------------------------------------------------------------- | ------------------------------------ | ------------- |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTGENERATEHTMLIN` | Threads for HTML document generation | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTPERSISTIN`      | Threads for document persistence     | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTSPLITIN`        | Threads for document splitting       | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTGETURLSIN`      | Threads for document URL retrieval   | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_OCRIN`                  | Threads for OCR processing           | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEDELETEIN`           | Threads for file deletion            | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEUPDATEIN`           | Threads for file updates             | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILECONVERTIN`          | Threads for file conversion          | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEPERSISTIN`          | Threads for file persistence         | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILECOMBINEIN`          | Threads for file combining           | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEENCRYPTIN`          | Threads for file encryption          | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEDECRYPTIN`          | Threads for file decryption          | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN`          | Threads for file archive             | `5`           |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEEXTRACTIN`          | Threads for file extract             | `5`           |

***

## Document topics

### Generate HTML documents

| Environment Variable                     | Description                                 | Default Value                                                      |
| ---------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ |
| `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN`  | Topic for incoming HTML generation requests | `ai.flowx.plugin.document.trigger.generate.html.v1`                |
| `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT` | Topic for HTML generation results           | `ai.flowx.engine.receive.plugin.document.generate.html.results.v1` |

### Document persistence

| Environment Variable               | Description                                      | Default Value                                                         |
| ---------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_IN`  | Topic for incoming document persistence requests | `ai.flowx.plugin.document.trigger.persist.document.v1`                |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_OUT` | Topic for document persistence results           | `ai.flowx.engine.receive.plugin.document.persist.document.results.v1` |

### Document splitting

| Environment Variable             | Description                                    | Default Value                                                       |
| -------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| `KAFKA_TOPIC_DOCUMENT_SPLIT_IN`  | Topic for incoming document splitting requests | `ai.flowx.plugin.document.trigger.split.document.v1`                |
| `KAFKA_TOPIC_DOCUMENT_SPLIT_OUT` | Topic for document splitting results           | `ai.flowx.engine.receive.plugin.document.split.document.results.v1` |

### Document URL retrieval

| Environment Variable                | Description                               | Default Value                                             |
| ----------------------------------- | ----------------------------------------- | --------------------------------------------------------- |
| `KAFKA_TOPIC_DOCUMENT_GET_URLS_IN`  | Topic for incoming URL retrieval requests | `ai.flowx.plugin.document.retrieve.urls.v1`               |
| `KAFKA_TOPIC_DOCUMENT_GET_URLS_OUT` | Topic for URL retrieval results           | `ai.flowx.engine.receive.plugin.document.urls.results.v1` |

### OCR processing

| Environment Variable  | Description                      | Default Value                                            |
| --------------------- | -------------------------------- | -------------------------------------------------------- |
| `KAFKA_TOPIC_OCR_IN`  | Topic for incoming OCR requests  | `ai.flowx.plugin.document.store.ocr.v1`                  |
| `KAFKA_TOPIC_OCR_OUT` | Topic for OCR processing results | `ai.flowx.engine.receive.plugin.document.ocr.results.v1` |

***

## File operation topics

### File deletion

| Environment Variable          | Description                               | Default Value                                                    |
| ----------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_DELETE_IN`  | Topic for incoming file deletion requests | `ai.flowx.plugin.document.trigger.delete.file.v1`                |
| `KAFKA_TOPIC_FILE_DELETE_OUT` | Topic for file deletion results           | `ai.flowx.engine.receive.plugin.document.delete.file.results.v1` |

### File update

| Environment Variable          | Description                             | Default Value                                                    |
| ----------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_UPDATE_IN`  | Topic for incoming file update requests | `ai.flowx.plugin.document.trigger.update.file.v1`                |
| `KAFKA_TOPIC_FILE_UPDATE_OUT` | Topic for file update results           | `ai.flowx.engine.receive.plugin.document.update.file.results.v1` |

### File conversion

| Environment Variable           | Description                                 | Default Value                                                     |
| ------------------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_CONVERT_IN`  | Topic for incoming file conversion requests | `ai.flowx.plugin.document.trigger.convert.file.v1`                |
| `KAFKA_TOPIC_FILE_CONVERT_OUT` | Topic for file conversion results           | `ai.flowx.engine.receive.plugin.document.convert.file.results.v1` |

### File persistence

| Environment Variable           | Description                                  | Default Value                                                     |
| ------------------------------ | -------------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_PERSIST_IN`  | Topic for incoming file persistence requests | `ai.flowx.plugin.document.trigger.persist.file.v1`                |
| `KAFKA_TOPIC_FILE_PERSIST_OUT` | Topic for file persistence results           | `ai.flowx.engine.receive.plugin.document.persist.file.results.v1` |

### File combination

| Environment Variable           | Description                                  | Default Value                                                     |
| ------------------------------ | -------------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_COMBINE_IN`  | Topic for incoming file combination requests | `ai.flowx.plugin.document.trigger.combine.file.v1`                |
| `KAFKA_TOPIC_FILE_COMBINE_OUT` | Topic for file combination results           | `ai.flowx.engine.receive.plugin.document.combine.file.results.v1` |

### File encryption

| Environment Variable           | Description                                 | Default Value                                                     |
| ------------------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_ENCRYPT_IN`  | Topic for incoming file encryption requests | `ai.flowx.plugin.document.trigger.encrypt.file.v1`                |
| `KAFKA_TOPIC_FILE_ENCRYPT_OUT` | Topic for file encryption results           | `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` |

### File decryption

| Environment Variable           | Description                                 | Default Value                                                     |
| ------------------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_DECRYPT_IN`  | Topic for incoming file decryption requests | `ai.flowx.plugin.document.trigger.decrypt.file.v1`                |
| `KAFKA_TOPIC_FILE_DECRYPT_OUT` | Topic for file decryption results           | `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` |

### File archive

Bundle a list of `fileId`s into a single (optionally password-protected) ZIP, persisted as a new Document/File. Uses the same trigger/reply pattern as encryption.

| Environment Variable           | Description                              | Default Value                                                     |
| ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_ARCHIVE_IN`  | Topic for incoming file archive requests | `ai.flowx.plugin.document.trigger.archive.file.v1`                |
| `KAFKA_TOPIC_FILE_ARCHIVE_OUT` | Topic for file archive results           | `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` |

### File extract

Unpack a ZIP `fileId` into N persisted Documents/Files. Supports plain and password-protected archives.

| Environment Variable           | Description                              | Default Value                                                     |
| ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------- |
| `KAFKA_TOPIC_FILE_EXTRACT_IN`  | Topic for incoming file extract requests | `ai.flowx.plugin.document.trigger.extract.file.v1`                |
| `KAFKA_TOPIC_FILE_EXTRACT_OUT` | Topic for file extract results           | `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` |

### Bulk document persistence

| Environment Variable                    | Description                                  | Default Value                                                              |
| --------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_BULK_IN`  | Topic for incoming bulk document persistence | `ai.flowx.plugin.document.trigger.persist.document.bulk.v1`                |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_BULK_OUT` | Topic for bulk document persistence results  | `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` |

### UI flow session variable updates

After a UI Flow session document upload completes, the document-plugin sends the result to the process-engine so the session variables are updated automatically.

| Environment Variable            | Description                                                                                      | Default Value                             |
| ------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending document upload results to process-engine for UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` |

### UI Flow multi-file upload

When a UI Flow uploads several files at once, the process-engine sends a single bulk command to document-plugin instead of one command per file. The document-plugin persists each file in the session and emits a single SSE frame (`eventType=UI_FLOW_FILE_UPLOAD_MULTIPLE`, `namespace=uploadBatchId`) at the end of the batch via events-gateway, then forwards the per-file results to `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`.

| Environment Variable                           | Description                                                                                  | Default Value                                                       |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` |

***

## Audit

| Environment Variable    | Description                  | Default Value                         |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### General storage configuration

| Environment Variable                        | Description                                                                                 | Default Value     |
| ------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------- |
| `APPLICATION_DEFAULTLOCALE`                 | Default locale for the application                                                          | `en`              |
| `APPLICATION_SUPPORTEDLOCALES`              | Comma-separated list of supported locales                                                   | `en, ro`          |
| `APPLICATION_FILESTORAGE_TYPE`              | Storage type to use (`s3` or `fileSystem`)                                                  | `s3`              |
| `APPLICATION_FILESTORAGE_DISKDIRECTORY`     | Directory for file storage when using filesystem                                            | `MS_SVC_DOCUMENT` |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | Strategy for file organization (`NONE` or `PROCESS_DATE`)                                   | `NONE`            |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY`  | Strategy for deleting files (`delete`, `disabled`, or `deleteBypassingGovernanceRetention`) | `delete`          |
| `APPLICATION_FILESTORAGE_TESTFILESBUCKET`   | Custom bucket name for test files (overrides default `-test-documents` suffix)              | `-test-documents` |

<Info>
  `APPLICATION_FILESTORAGE_DELETIONSTRATEGY`:

  * `disabled`: This will disable entirely the deletion of temporary files from the temporary bucket, and the responsibility to delete and clean up the bucket will move in the ownership of the admins of the implementing project.
  * `deleteBypassingGovernanceRetention`: This will still delete the temporary files and further more will add in the delete request the header: `x-amz-bypass-governance-retention:true` , to enable deletion of governed files, in case the s3 configured user for document-plugin, will have the `s3:BypassGovernanceRetention` permission.
</Info>

<Info>
  `APPLICATION_FILESTORAGE_TESTFILESBUCKET`: This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed. This is particularly useful when the client environment has restrictions on bucket naming conventions or doesn't have permissions to create new buckets.
</Info>

### Runtime buckets configuration

| Environment Variable                                        | Description                                             | Default Value    |
| ----------------------------------------------------------- | ------------------------------------------------------- | ---------------- |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_ENABLED`         | Enable dedicated runtime buckets for file storage       | `false`          |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_BUCKETNAME`      | Name of the runtime bucket                              | `runtime-bucket` |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_PARTITIONBYDATE` | Enable date-based partitioning for runtime bucket files | `true`           |

### Zip extraction configuration

| Environment Variable               | Description                                                    | Default Value                                |
| ---------------------------------- | -------------------------------------------------------------- | -------------------------------------------- |
| `ZIP_EXTRACTION_ALLOWEDEXTENSIONS` | Comma-separated list of allowed file extensions in ZIP uploads | `pdf,xls,xlsx,doc,docx,txt,jpg,jpeg,png,gif` |

***

## S3-Compatible storage configuration

| Environment Variable                           | Description                                       | Default Value                 |
| ---------------------------------------------- | ------------------------------------------------- | ----------------------------- |
| `APPLICATION_FILESTORAGE_S3_ENABLED`           | Enable S3-compatible storage                      | `true`                        |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`         | URL of S3-compatible server                       | `http://minio-service:9000`   |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY`         | Access key for S3                                 | `minio`                       |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY`         | Secret key for S3                                 | `secret`                      |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`      | Prefix for bucket names                           | `qdevlocal-preview-paperflow` |
| `APPLICATION_FILESTORAGE_S3_TEMPBUCKET`        | Name of temporary bucket for initial file uploads | `temp-bucket`                 |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable server-side encryption                     | `false`                       |

<Info>
  Make sure to follow the recommended [bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) when choosing the bucket prefix name.
</Info>

***

## CAS lib configuration

| Environment Variable  | Description                  | Default Value   |
| --------------------- | ---------------------------- | --------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`       |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`         |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

***

## Logging configuration

| Environment Variable         | Description                                 | Default Value |
| ---------------------------- | ------------------------------------------- | ------------- |
| `LOGGING_LEVEL_APP`          | Log level for application logs              | `INFO`        |
| `LOGGING_LEVEL_MONGO_DRIVER` | Log level for MongoDB driver                | `INFO`        |
| `LOGGING_LEVEL_LIQUIBASE`    | Log level for Liquibase database migrations | `INFO`        |
| `LOGGING_LEVEL_REDIS`        | Log level for Redis/Lettuce client          | `OFF`         |
| `LOGGING_LEVEL_ROOT`         | Root logging level for the application      | -             |

***

## Ingress and CORS

The Document plugin is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/document`   | `/`              |
| public     | `/document`   | `/`              |

Paths are set through `services.document-plugin.ingress.admin.path` / `services.document-plugin.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values. The chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` by default on both routes to allow larger document uploads — adjust the annotation if you need a different limit.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                                            | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that uploads or fetches documents from the browser. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="File upload fails">
    **Symptoms:** File uploads return errors or time out.

    **Solutions:**

    1. Verify the S3/MinIO connection by checking `APPLICATION_FILESTORAGE_S3_SERVERURL`, `APPLICATION_FILESTORAGE_S3_ACCESSKEY`, and `APPLICATION_FILESTORAGE_S3_SECRETKEY`
    2. Ensure the target bucket exists and the configured user has read/write permissions
    3. Check that `SPRING_SERVLET_MULTIPART_MAXFILESIZE` is large enough for the files being uploaded
    4. Verify network connectivity between the pod and the S3-compatible storage service
  </Accordion>

  <Accordion title="Document generation not working">
    **Symptoms:** HTML-to-PDF document generation fails or produces empty documents.

    **Solutions:**

    1. Verify `FLOWX_HTML_TEMPLATES_ENABLED` is set to `true`
    2. Check that the font paths in `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` are valid and the font files exist at those paths
    3. Ensure the Kafka topics for HTML generation (`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN` / `OUT`) are created and accessible
    4. Verify MongoDB connectivity, as HTML templates are stored in MongoDB
  </Accordion>

  <Accordion title="Files not being deleted from temporary storage">
    **Symptoms:** The temporary S3 bucket grows continuously and files are not cleaned up.

    **Solutions:**

    1. Check that `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` is set to `delete` (not `disabled`)
    2. If using governance-locked buckets, set the strategy to `deleteBypassingGovernanceRetention` and ensure the S3 user has the `s3:BypassGovernanceRetention` permission
    3. Verify the temporary bucket name configured in `APPLICATION_FILESTORAGE_S3_TEMPBUCKET` matches the actual bucket
    4. Check application logs for deletion errors or permission issues
  </Accordion>

  <Accordion title="PDF conversion fails">
    **Symptoms:** File conversion requests fail or return errors.

    **Solutions:**

    1. Check that the source file format is in the supported list configured via `ZIP_EXTRACTION_ALLOWEDEXTENSIONS`
    2. Verify `FLOWX_CONVERT_DPI` is set to a valid value (default `150`)
    3. Ensure the file is not corrupted and uses valid encoding
    4. Check that the Kafka topics for file conversion (`KAFKA_TOPIC_FILE_CONVERT_IN` / `OUT`) are properly configured
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Uploading Documents" icon="cloud-arrow-up" href="../docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document">
    Upload documents to processes using the Documents plugin
  </Card>

  <Card title="Generating Documents" icon="file-pdf" href="../docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates">
    Generate documents from HTML templates
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>
</CardGroup>


# Email Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/email-gateway-setup

This guide provides step-by-step instructions for setting up the Email Gateway microservice.

The Email Gateway is a FlowX.AI microservice that handles email communication workflows. It is available as a Docker image and requires specific infrastructure components to function properly.

## Dependencies

Before setting up the Email Gateway, ensure you have the following dependencies in place:

* **PostgreSQL** database for storing email gateway data
* **MongoDB** connection to the app-runtime database for runtime data access
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization

<Info>
  The Email Gateway does not require an ingress configuration as it operates as an internal service communicating via Kafka.
</Info>

## Infrastructure prerequisites

| Component  | Description                                     |
| ---------- | ----------------------------------------------- |
| PostgreSQL | Dedicated database named `email_gateway`        |
| MongoDB    | Shared connection to the `app-runtime` database |
| Kafka      | Message broker for inter-service communication  |
| Redis      | Caching layer for improved performance          |
| Keycloak   | Identity provider for service authentication    |

***

## Configuration

### Authorization configuration

The Email Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-email-gateway-sa`                                                                           |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### PostgreSQL configuration

The Email Gateway uses its own dedicated PostgreSQL database for storing email-related data.

| Environment Variable         | Description                        | Default Value                                     |
| ---------------------------- | ---------------------------------- | ------------------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/email_gateway` |
| `SPRING_DATASOURCE_USERNAME` | Database username                  | `flowx`                                           |
| `SPRING_DATASOURCE_PASSWORD` | Database password                  | -                                                 |

<Warning>
  Ensure the `email_gateway` database is created before deploying the service. The Email Gateway will manage its own schema migrations.
</Warning>

### MongoDB configuration (app-runtime)

The Email Gateway connects to the shared `app-runtime` MongoDB database for accessing runtime data.

| Environment Variable              | Description                            | Default Value                                                                                                                                                                  |
| --------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | MongoDB connection URI for app-runtime | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME`                     | MongoDB username                       | `app-runtime`                                                                                                                                                                  |
| `DB_PASSWORD`                     | MongoDB password                       | -                                                                                                                                                                              |

<Info>
  The `retryWrites=false` parameter is required for compatibility with MongoDB replica set configurations that include arbiters.
</Info>

### Redis configuration

Email Gateway uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

### Kafka configuration

#### Core Kafka settings

| Environment Variable               | Description                                             | Default Value      |
| ---------------------------------- | ------------------------------------------------------- | ------------------ |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS`   | Address of the Kafka server(s)                          | `localhost:9092`   |
| `SPRING_KAFKA_SECURITY_PROTOCOL`   | Security protocol for Kafka connections                 | `PLAINTEXT`        |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size (bytes)                            | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10`               |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

### IMAP configuration

Configure the Email Gateway's IMAP polling behavior for inbound email processing:

| Environment Variable                       | Description                                          | Default Value |
| ------------------------------------------ | ---------------------------------------------------- | ------------- |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT`    | IMAP server connection timeout in milliseconds       | `10000`       |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS`  | Maximum number of concurrent IMAP polling operations | `30`          |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle          | `50`          |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL`      | Interval between IMAP polling cycles in seconds      | `30`          |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT`          | IMAP read timeout in milliseconds                    | `30000`       |

### Microsoft Graph configuration

| Environment Variable                           | Description                                          | Default Value |
| ---------------------------------------------- | ---------------------------------------------------- | ------------- |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50`          |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL`      | TTL for cached MS Graph client instances             | `1d`          |

<Tip>
  The client cache TTL controls how long authenticated MS Graph client instances are kept in memory before being refreshed. Increase this value in stable environments to reduce token refresh overhead.
</Tip>

### Master election configuration

The Email Gateway uses a master election mechanism to coordinate work across multiple replicas:

| Environment Variable                 | Description                                | Default Value   |
| ------------------------------------ | ------------------------------------------ | --------------- |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL`  | Master election TTL in seconds             | `15`            |

### Rebalancing configuration

Configure how email accounts are distributed across service instances:

| Environment Variable                    | Description                                            | Default Value    |
| --------------------------------------- | ------------------------------------------------------ | ---------------- |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance            | `100`            |
| `EMAIL_GATEWAY_REBALANCING_CRON`        | Cron expression for email account rebalancing          | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS`   | Timeout in seconds before marking an instance as stale | `90`             |

### Kafka topics

The Email Gateway publishes to the following Kafka topics:

| Environment Variable            | Description                                           | Default Value                                      |
| ------------------------------- | ----------------------------------------------------- | -------------------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT`         | Topic for audit event logging                         | `ai.flowx.core.trigger.save.audit.v1`              |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for triggering process starts from email events | `ai.flowx.core.trigger.start-for-event.process.v1` |

### Logging configuration

Control logging levels for different components:

| Environment Variable  | Description                          | Default Value |
| --------------------- | ------------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT`  | Root logging level                   | `INFO`        |
| `LOGGING_LEVEL_APP`   | Application-specific log level       | `DEBUG`       |
| `LOGGING_CONFIG_FILE` | Path to external logging config file | -             |

***

## Secrets management

The Email Gateway requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name                                                            | Description                                |
| ---------------------------------------------------------------------- | ------------------------------------------ |
| `SPRING_DATASOURCE_PASSWORD`                                           | PostgreSQL database password               |
| `DB_PASSWORD`                                                          | MongoDB password for app-runtime access    |
| `SPRING_REDIS_PASSWORD`                                                | Redis authentication password              |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret            |
| `KAFKA_OAUTH_CLIENT_SECRET`                                            | Kafka OAuth client secret (if using OAuth) |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the Email Gateway:

```yaml theme={"system"}
fullnameOverride: email-gateway

image:
  repository: <your-registry>/email-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production
  
  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/email_gateway
  SPRING_DATASOURCE_USERNAME: flowx
  
  # MongoDB (app-runtime)
  SPRING_DATA_MONGODB_RUNTIME_URI: "mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false"
  DB_USERNAME: app-runtime
  
  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092
  KAFKA_OAUTH_CLIENT_ID: kafka-client
  KAFKA_OAUTH_TOKEN_ENDPOINT_URI: https://keycloak.example.com/auth/realms/kafka-authz/protocol/openid-connect/token
  
  # OAuth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
  SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID: flowx-email-gateway-sa
  
  # Redis
  SPRING_REDIS_HOST: redis-master

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: mongodb-generic
    secrets:
      DB_PASSWORD: mongodb-password
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakEmailGatewayClientSecret

rbac:
  create: true

# Email Gateway does not expose HTTP endpoints externally
ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/egress-s-mongodb: "true"
  flowx.ai/routing-name: "email-gateway"
  flowx.ai/prometheus-scrape: "email-gateway"
```

### Network policies

The Email Gateway requires network access to the following services:

| Service    | Purpose                      | Pod Label                      |
| ---------- | ---------------------------- | ------------------------------ |
| Kafka      | Message broker communication | `flowx.ai/egress-s-kafka`      |
| PostgreSQL | Primary data storage         | `flowx.ai/egress-s-postgresql` |
| MongoDB    | App-runtime data access      | `flowx.ai/egress-s-mongodb`    |

***

## Monitoring

The Email Gateway exposes Prometheus metrics for monitoring. Enable scraping by setting the pod label:

```yaml theme={"system"}
podLabels:
  flowx.ai/prometheus-scrape: "email-gateway"
```

### Health endpoints

| Endpoint            | Description                 |
| ------------------- | --------------------------- |
| `/actuator/health`  | Health check endpoint       |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info`    | Application info endpoint   |

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify the `email_gateway` database exists in PostgreSQL
    2. Check that the database user has appropriate permissions
    3. Ensure network connectivity between the pod and PostgreSQL service
    4. Verify the JDBC URL format is correct
  </Accordion>

  <Accordion title="MongoDB connection issues">
    **Symptoms:** Errors accessing app-runtime data.

    **Solutions:**

    1. Verify MongoDB replica set is healthy
    2. Check that `retryWrites=false` is set in the connection URI
    3. Ensure the MongoDB user has read access to the `app-runtime` database
    4. Verify network policies allow MongoDB traffic
  </Accordion>

  <Accordion title="Kafka authentication failures">
    **Symptoms:** Kafka consumer/producer fails to connect.

    **Solutions:**

    1. Verify OAuth token endpoint is accessible
    2. Check Kafka OAuth client credentials
    3. Ensure the `kafka-authz` realm exists in Keycloak
    4. Verify network connectivity to both Kafka and Keycloak
  </Accordion>

  <Accordion title="Service account authentication errors">
    **Symptoms:** 401/403 errors when calling other FlowX services.

    **Solutions:**

    1. Verify the Keycloak service account is properly configured
    2. Check that client secrets match between configuration and Keycloak
    3. Ensure the service account has required roles assigned
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Email Trigger" icon="envelope-open-text" href="/5.9/docs/platform-deep-dive/integrations/email-trigger">
    Configure IMAP connections to trigger processes from incoming emails
  </Card>

  <Card title="Email Sender" icon="paper-plane" href="/5.9/docs/platform-deep-dive/integrations/email-sender">
    Configure SMTP connections to send emails from processes
  </Card>

  <Card title="Microsoft Outlook" icon="envelope" href="/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source">
    Connect to Outlook via MS Graph API for reading and sending emails
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# FlowX Events Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/events-gateway-setup

This guide will walk you through the process of setting up the events-gateway service.

## Infrastructure prerequisites

Before proceeding with the setup, ensure that the following components have been set up:

* **Redis**
* **Kafka**

***

## Configuration

### Configuring Kafka

Set the following Kafka-related configurations using environment variables:

| Configuration Parameter            | Default Value    | Description                                                              |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------ |
| `KAFKA_BOOTSTRAP_SERVERS`          | `localhost:9092` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)      |
| `KAFKA_SECURITY_PROTOCOL`          | `PLAINTEXT`      | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) |
| `KAFKA_MESSAGE_MAX_BYTES`          | `52428800`       | Maximum message size in bytes (50 MB)                                    |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | `10`             | Retry interval for auth exceptions (seconds)                             |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Topic naming configuration

| Configuration Parameter          | Default Value | Description                         |
| -------------------------------- | ------------- | ----------------------------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | `ai.flowx.`   | Package prefix for topic names      |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | ` `           | Environment segment for topic names |
| `KAFKA_TOPIC_NAMING_VERSION`     | `.v1`         | Version suffix for topic names      |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | `.`           | Primary separator for topic names   |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | `-`           | Secondary separator for topic names |

#### Group IDs

The configuration parameters "KAFKA\_CONSUMER\_GROUPID\_\*" are used to set the consumer group name for Kafka consumers that consume messages from topics. Consumer groups in Kafka allow for parallel message processing by distributing the workload among multiple consumer instances. By configuring the consumer group ID, you can specify the logical grouping of consumers that work together to process messages from the same topic, enabling scalable and fault-tolerant message consumption in your Kafka application.

| Configuration Parameter                                   | Default value                     | Description                                                          |
| --------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------- |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_MESSAGE`    | `engine-commands-message`         | Consumer group ID for processing engine commands messages            |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_DISCONNECT` | `engine-commands-disconnect`      | Consumer group ID for processing engine commands disconnect messages |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_CONNECT`    | `engine-commands-connect`         | Consumer group ID for processing engine commands connect messages    |
| `KAFKA_CONSUMER_GROUPID_TASKCOMMANDS_MESSAGE`             | `task-commands-message`           | Consumer group ID for processing task commands messages              |
| `KAFKA_CONSUMER_GROUPID_PROCESSCOMMANDS_MESSAGE`          | `process-commands-message`        | Consumer group ID for processing process commands messages           |
| `KAFKA_CONSUMER_GROUPID_GENERICCOMMANDS`                  | `generic-commands-message`        | Consumer group ID for processing generic commands messages           |
| `KAFKA_CONSUMER_GROUPID_USERBROADCASTCOMMANDS`            | `user-broadcast-commands-message` | Consumer group ID for processing user broadcast commands messages    |

#### Threads

The configuration parameters "KAFKA\_CONSUMER\_THREADS\_\*" are utilized to specify the number of threads assigned to Kafka consumers for processing messages from topics. These parameters allow you to fine-tune the concurrency and parallelism of your Kafka consumer application, enabling efficient and scalable message consumption from Kafka topics.

| Configuration Parameter                                   | Default value | Description                                                          |
| --------------------------------------------------------- | ------------- | -------------------------------------------------------------------- |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_MESSAGE`    | `10`          | Number of threads for processing engine commands messages            |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_DISCONNECT` | `5`           | Number of threads for processing engine commands disconnect messages |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_CONNECT`    | `5`           | Number of threads for processing engine commands connect messages    |
| `KAFKA_CONSUMER_THREADS_TASKCOMMANDS`                     | `10`          | Number of threads for task commands messages                         |
| `KAFKA_CONSUMER_THREADS_PROCESSCOMMANDS`                  | `10`          | Number of threads for processing process commands messages           |
| `KAFKA_CONSUMER_THREADS_GENERICCOMMANDS`                  | `10`          | Number of threads for processing generic commands messages           |
| `KAFKA_CONSUMER_THREADS_USERBROADCASTCOMMANDS`            | `10`          | Number of threads for processing user broadcast commands messages    |

#### Events Gateway pattern

| Configuration Parameter             | Default value                      | Description                              |
| ----------------------------------- | ---------------------------------- | ---------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_PATTERN` | `ai.flowx.eventsgateway.receive.*` | Pattern for Events Gateway communication |

#### Kafka topics related to process instances

| Configuration Parameter                                   | Default value                                          | Description                                   |
| --------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_MESSAGE`    | `ai.flowx.eventsgateway.engine.commands.message.v1`    | Topic for engine commands messages            |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_DISCONNECT` | `ai.flowx.eventsgateway.engine.commands.disconnect.v1` | Topic for engine commands disconnect messages |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_CONNECT`    | `ai.flowx.eventsgateway.engine.commands.connect.v1`    | Topic for engine commands connect messages    |

#### Kafka topics related to process commands

| Configuration Parameter                        | Default value                                        | Description                         |
| ---------------------------------------------- | ---------------------------------------------------- | ----------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESS_IN_MESSAGE` | `ai.flowx.eventsgateway.process.commands.message.v1` | Topic for process commands messages |

#### Kafka topics related to user messages

| Configuration Parameter                             | Default value                                 | Description                          |
| --------------------------------------------------- | --------------------------------------------- | ------------------------------------ |
| `KAFKA_TOPIC_EVENTSGATEWAY_USERMESSAGES_IN_MESSAGE` | `ai.flowx.core.designer.notification.user.v1` | Topic for user notification messages |

### Configuring authorization & access roles

Events Gateway validates incoming tokens with the JWT public key mechanism:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                          |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                       |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`       |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                        |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### Service communication

| Environment Variable        | Description                             | Default Value             |
| --------------------------- | --------------------------------------- | ------------------------- |
| `FLOWX_URLS_RUNTIMEMANAGER` | Base URL of the Runtime Manager service | `http://runtime-manager/` |

### Redis configuration

FlowX Events Gateway uses Redis for real-time message distribution. The process engine sends messages to the events-gateway, which is responsible for sending them to Redis.

Events Gateway supports all Redis deployment modes (Standalone, Sentinel, and Cluster). For detailed Redis configuration including all deployment modes and parameters, see the [Redis Configuration](/5.9/setup-guides/redis-configuration) guide.

#### Quick reference

Common Redis configuration parameters:

| Configuration Parameter             | Description                             | Example Value             |
| ----------------------------------- | --------------------------------------- | ------------------------- |
| `SPRING_DATA_REDIS_HOST`            | Redis server hostname (Standalone mode) | `localhost`               |
| `SPRING_DATA_REDIS_PORT`            | Redis server port (Standalone mode)     | `6379`                    |
| `SPRING_DATA_REDIS_PASSWORD`        | Redis authentication password           | `yourpassword`            |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Sentinel master name (Sentinel mode)    | `mymaster`                |
| `SPRING_DATA_REDIS_SENTINEL_NODES`  | Sentinel nodes (Sentinel mode)          | `host1:26379,host2:26379` |
| `SPRING_DATA_REDIS_CLUSTER_NODES`   | Cluster nodes (Cluster mode)            | `host1:6379,host2:6379`   |

<Info>
  For complete Redis configuration details including Sentinel mode, Cluster mode, SSL/TLS setup, and troubleshooting, refer to the [Redis Configuration guide](/5.9/setup-guides/redis-configuration).
</Info>

### Events

This configuration helps manage how event data is stored and accessed in Redis.

| Configuration Parameter        | Default | Description                                                                                           |
| ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `EVENTS_REDIS_FREQUENCYMILLIS` | 300     | Time interval (in milliseconds) between Redis queries by the events gateway to check for new messages |
| `EVENTS_REDIS_TTLHOURS`        | 4       | Sets the time-to-live for events in Redis to 4 hours                                                  |

### SSE cleanup configuration

Configure how Server-Sent Events (SSE) connections are cleaned up:

| Configuration Parameter              | Default | Description                                                         |
| ------------------------------------ | ------- | ------------------------------------------------------------------- |
| `EVENTS_SSE_CLEANUP_INTERVALMINUTES` | `5`     | Interval in minutes between SSE connection cleanup cycles           |
| `EVENTS_SSE_CLEANUP_MAXAGEMINUTES`   | `10`    | Maximum age in minutes before an inactive SSE connection is removed |

### Configuring logging

The following environment variables control log levels:

| Configuration Parameter | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `LOGGING_LEVEL_ROOT`    | Logging level for the root Spring Boot microservice logs |
| `LOGGING_LEVEL_APP`     | Logging level for the application-level logs             |

***

## Ingress and CORS

The Events Gateway is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. The path is preserved end-to-end (no rewrite), because Server-Sent Events use the same path on the backend as on the client.

### Service routes

| Host group | External path | Backend receives  | Notes          |
| ---------- | ------------- | ----------------- | -------------- |
| admin      | `/api/events` | `/api/events/...` | Path preserved |
| public     | `/api/events` | `/api/events/...` | Path preserved |

Paths are set through `services.events-gateway.ingress.admin.path` / `services.events-gateway.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values. No rewrite is applied because Events Gateway expects the same path on the backend.

<Note>
  Server-Sent Events are long-lived HTTP connections. If you front Events Gateway with a custom ingress controller or reverse proxy, set generous read timeouts (300s+) and disable response buffering on the SSE path.
</Note>

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                   | Default Value |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to open SSE connections from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that subscribes to events. | `-`           |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults for SSE traffic. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="SSE connections dropping unexpectedly">
    **Symptoms:** Clients lose real-time updates intermittently, SSE connections close after a timeout period.

    **Solutions:**

    1. Check your ingress timeout settings — SSE connections require longer timeouts than standard HTTP requests. Set `proxy-read-timeout` and `proxy-send-timeout` to at least `3600` seconds
    2. Verify keep-alive configuration on your load balancer and ingress controller
    3. Review the `EVENTS_SSE_CLEANUP_MAXAGEMINUTES` setting — ensure it is not set too low for your use case
    4. Check for network proxies or firewalls that may terminate long-lived connections
  </Accordion>

  <Accordion title="Events not reaching the UI">
    **Symptoms:** Process updates do not appear in the Designer or end-user interface, despite successful process execution.

    **Solutions:**

    1. Verify Kafka consumer configuration — check that the consumer group IDs match expected values
    2. Confirm that the `KAFKA_TOPIC_EVENTSGATEWAY_PATTERN` matches the topics being published to by the process engine
    3. Check Kafka consumer lag using your monitoring tools to identify backpressure issues
    4. Ensure the events-gateway service has network access to Kafka brokers
  </Accordion>

  <Accordion title="High latency on events">
    **Symptoms:** Noticeable delay between process execution and UI updates.

    **Solutions:**

    1. Check the Redis connection — verify `SPRING_DATA_REDIS_HOST` and `SPRING_DATA_REDIS_PORT` are correct and the Redis instance is responsive
    2. Review `EVENTS_REDIS_FREQUENCYMILLIS` — lower values reduce latency but increase Redis load
    3. Check Kafka partition configuration — ensure sufficient partitions for your consumer thread count
    4. Monitor Kafka consumer thread counts (`KAFKA_CONSUMER_THREADS_*`) and increase if threads are saturated
  </Accordion>

  <Accordion title="WebSocket connection failures">
    **Symptoms:** Browser console shows WebSocket or SSE connection errors, CORS-related error messages.

    **Solutions:**

    1. Verify CORS settings in your ingress configuration allow the Designer and application domains
    2. Ensure the ingress controller supports WebSocket upgrades and SSE connections
    3. Check that the ingress path pattern `/api/events(/|$)(.*)(/|$)(.*)` is correctly configured
    4. Confirm that the `events-gateway` service is reachable from the ingress controller
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Ingress Configuration" icon="globe" href="./ingress-configuration">
    Configure routing, CORS, and SSE-specific ingress settings
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="FlowX Engine Setup" icon="engine" href="./flowx-engine-setup-guide/engine-setup">
    Configure the process engine that publishes events to the gateway
  </Card>
</CardGroup>


# File Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/file-gateway-setup

Set up the File Gateway microservice — ingests files from FTP, SFTP, S3, and Azure Blob storage into FlowX workflows, delivers generated files back, and can trigger processes when new files arrive.

<Info>
  The File Gateway lets workflows exchange files with external storage systems (FTP, SFTP, S3, Azure Blob) and start processes when new files land in a watched location.
</Info>

## Dependencies

Before setting up the File Gateway, ensure you have the following dependencies in place:

* **MongoDB** for storing file-trigger definitions and poll state
* **Kafka** for publishing process start events
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained, workspace-level authorization
* **Document service** for storing ingested and generated files
* **File storage targets** — the FTP, SFTP, S3, or Azure Blob systems you connect to (credentials are tenant-supplied per connection, not set as service env vars)

## Infrastructure prerequisites

| Component | Description                                                                                                                  |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| MongoDB   | Stores `file_triggers`, `seen_file_cursors`, `failed_files`, `poll_leases` collections (shares the runtime MongoDB instance) |
| Kafka     | Message broker for triggering process starts                                                                                 |
| Keycloak  | Identity provider for service authentication                                                                                 |
| SpiceDB   | Authorization service for workspace validation                                                                               |
| Document  | Receives uploaded files via the document service internal API                                                                |

***

## Configuration

### Authorization configuration

The File Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-file-gateway-sa`                                                                            |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

***

### MongoDB configuration

The File Gateway uses the runtime MongoDB instance (the same one used by the Email Gateway) to store file-trigger definitions and polling state.

| Environment Variable      | Description            | Default Value |
| ------------------------- | ---------------------- | ------------- |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | -             |

***

### Kafka configuration

The File Gateway publishes a process-start event when a watched location receives a new file (a file trigger).

#### Core Kafka settings

| Environment Variable             | Description                             | Default Value    |
| -------------------------------- | --------------------------------------- | ---------------- |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s)          | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections | `PLAINTEXT`      |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Kafka topics

| Environment Variable            | Description                                              | Default Value                                      |
| ------------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for starting a process when a watched file arrives | `ai.flowx.core.trigger.start-for-event.process.v1` |

***

### CAS lib configuration (SpiceDB)

| Environment Variable                         | Description                                                                                        | Default Value |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`                         | SpiceDB hostname                                                                                   | `spicedb`     |
| `FLOWX_SPICEDB_PORT`                         | SpiceDB gRPC port                                                                                  | `50051`       |
| `FLOWX_SPICEDB_TOKEN`                        | SpiceDB authentication token                                                                       | -             |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. Keep the default unless instructed by FlowX. | `CUSTOM`      |

***

### Service communication

The File Gateway communicates with the following FlowX services:

| Environment Variable                                       | Description                                           | Default Value                    |
| ---------------------------------------------------------- | ----------------------------------------------------- | -------------------------------- |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`  | Organization Manager base URL                         | `http://organization-manager:80` |
| `FLOWX_LIB_CASCLIENT_SERVICES_AUTHORIZATIONSYSTEM_BASEURL` | Authorization System base URL                         | `http://authorization-system:80` |
| `FLOWX_DOCUMENTPLUGIN_BASEURL`                             | Document Plugin base URL used to store ingested files | `http://document-plugin:80`      |

***

### Logging configuration

| Environment Variable | Description                    | Default Value |
| -------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT` | Root logging level             | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-specific log level | `INFO`        |

***

## File storage connections

File storage targets (FTP, SFTP, S3, Azure Blob) are **not** configured through service environment variables. Each connection — including its host, path, and credentials — is defined per workspace in the FlowX Designer as a **File Storage** data source. Credentials are tenant-supplied and stored securely; the File Gateway never uses pod identity, IAM roles, or managed identities to reach a customer's storage.

Supported authentication methods:

| Protocol   | Authentication                      |
| ---------- | ----------------------------------- |
| FTP / FTPS | Username + password                 |
| SFTP       | Username + password, or private key |
| S3         | Access key + secret                 |
| Azure Blob | Shared key (access key)             |

***

## Secrets management

| Secret Name                                                            | Description                                   |
| ---------------------------------------------------------------------- | --------------------------------------------- |
| `SPRING_DATA_MONGODB_URI`                                              | MongoDB connection URI (contains credentials) |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret               |
| `FLOWX_SPICEDB_TOKEN`                                                  | SpiceDB authentication token                  |
| `KAFKA_OAUTH_CLIENT_SECRET`                                            | Kafka OAuth client secret (if using OAuth)    |

***

## Deployment

### Helm values example

```yaml theme={"system"}
fullnameOverride: file-gateway

image:
  repository: <your-registry>/file-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # OAuth2
  SECURITY_TYPE: oauth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

extraEnvVarsMultipleSecretsCustomKeys:
  - name: mongodb-generic
    secrets:
      SPRING_DATA_MONGODB_URI: mongodb-uri
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakFileGatewayClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/routing-name: "file-gateway"
  flowx.ai/prometheus-scrape: "file-gateway"
```

<Note>
  The File Gateway makes outbound connections to customer-managed FTP/SFTP/S3/Azure Blob endpoints. Ensure egress network policies allow traffic to those destinations.
</Note>

***

## Verify your setup

<Check>
  The File Gateway pod is running and healthy: `kubectl get pods -l app=file-gateway`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://file-gateway:8080/actuator/health`
</Check>

<Check>
  MongoDB collections appear (`file_triggers`, `seen_file_cursors`, `failed_files`, `poll_leases`) with the expected indexes
</Check>

<Check>
  SpiceDB connection is established — check pod logs for successful CAS client initialization
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Files are not picked up from a watched location">
    **Solutions:**

    1. Confirm the File Storage data source and file trigger are configured and toggled ON in the Designer
    2. Verify the connection credentials and path in the data source
    3. Check egress network policies allow the File Gateway to reach the storage host
    4. Review pod logs for poll or authentication errors
  </Accordion>

  <Accordion title="SpiceDB connection failures">
    **Solutions:**

    1. Verify SpiceDB is running and reachable at the configured host and port
    2. Check that the SpiceDB token is correct
    3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
  </Accordion>

  <Accordion title="Processes not starting from file triggers">
    **Solutions:**

    1. Verify Kafka bootstrap servers are reachable
    2. Check that the `ai.flowx.core.trigger.start-for-event.process.v1` topic exists
    3. Confirm the bound Message Start Event and active build for the process
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="SpiceDB Configuration" icon="shield-halved" href="./spicedb">
    Fine-grained authorization setup
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="Email Gateway setup" icon="envelope" href="./email-gateway-setup">
    The email-trigger gateway this service mirrors
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# License service setup
Source: https://docs.flowx.ai/5.9/setup-guides/license-engine-setup

Set up the License service (formerly License Engine) — manages platform and application licensing, subscription plans, feature quotas, and usage tracking across SaaS and self-hosted deployments.

## Dependencies

Before setting up the License service, ensure you have the following dependencies in place:

* **[Organization Manager](/5.9/setup-guides/organization-manager-setup)** for organization lifecycle events and realm resolution
* **PostgreSQL** database for storing license and usage data
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching and master election
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization

## Infrastructure prerequisites

| Component  | Description                                            |
| ---------- | ------------------------------------------------------ |
| PostgreSQL | Dedicated database for license data                    |
| Kafka      | Message broker for inter-service communication         |
| Redis      | Caching layer and distributed lock for master election |
| Keycloak   | Identity provider for service authentication           |
| SpiceDB    | Authorization service for fine-grained access control  |

***

## Configuration

### Authorization configuration

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                          |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                                             | Security type (JWT public key validation)                                                                                                             | `jwt-public-key`                       |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-license-sa`                     |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                        |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret. Must be the same value across every service that uses `flowx-anonymous-sa`.                                  |                                        |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | Organization manager URL                                                                                                                              | `http://organization-manager:80`       |

***

### PostgreSQL configuration

The License service uses its own dedicated PostgreSQL database.

| Environment Variable         | Description                        | Default Value                                   |
| ---------------------------- | ---------------------------------- | ----------------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC connection URL for PostgreSQL | `jdbc:postgresql://flowxlicensedb:5432/license` |
| `SPRING_DATASOURCE_USERNAME` | Database username                  | `postgres`                                      |
| `SPRING_DATASOURCE_PASSWORD` | Database password                  | -                                               |

<Note>
  **PostgreSQL and Redis credentials: plain env vars still work.** The License service is a standard Spring Boot service — it reads the `SPRING_DATASOURCE_*` and `SPRING_DATA_REDIS_*` environment variables shown here. The `postgresql.servers/credentials` and `redis.servers/credentials` blocks in the FlowX Helm chart's `values.yaml` are the chart's own secret-to-env-var mapping; they exist to template the same plain env vars from your secrets. You can keep injecting credentials through plain environment variables exactly as before.
</Note>

<Warning>
  Ensure the database is created before deploying the service. The License service will manage its own schema migrations via Liquibase.
</Warning>

***

### Redis configuration

The License service includes Redis in its configuration for caching and master election. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

<Note>
  Redis is configured but not actively used by the License service at this time. It is included as part of the standard Spring service setup and may be used in future versions.
</Note>

***

### Kafka configuration

#### Core Kafka settings

| Environment Variable             | Description                    | Default Value      |
| -------------------------------- | ------------------------------ | ------------------ |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092`   |
| `KAFKA_MESSAGE_MAX_BYTES`        | Maximum message size (bytes)   | `52428800` (50 MB) |

#### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

#### Kafka topics

The License service consumes events from the following topics:

| Topic               | Default Value                     | Description                                         |
| ------------------- | --------------------------------- | --------------------------------------------------- |
| License usage       | `ai.flowx.license.usage.v1`       | Receives usage reporting events from other services |
| Organization events | `ai.flowx.organization.events.v1` | Receives organization lifecycle events              |

#### Kafka consumer threads

| Environment Variable                         | Description                                   | Default Value |
| -------------------------------------------- | --------------------------------------------- | ------------- |
| `KAFKA_CONSUMER_THREADS_LICENSE_USAGE`       | Thread count for license usage consumer       | `6`           |
| `KAFKA_CONSUMER_THREADS_ORGANIZATION_EVENTS` | Thread count for organization events consumer | `2`           |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`           | Retry interval after auth exception (seconds) | `10`          |

***

### CAS lib configuration (SpiceDB)

| Environment Variable                         | Description                                                                                                                                                                             | Default Value |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`                         | SpiceDB hostname                                                                                                                                                                        | `spicedb`     |
| `FLOWX_SPICEDB_PORT`                         | SpiceDB gRPC port                                                                                                                                                                       | `50051`       |
| `FLOWX_SPICEDB_TOKEN`                        | SpiceDB authentication token                                                                                                                                                            | -             |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM`      |

***

### FlowX SaaS connection (self-hosted only)

| Environment Variable           | Description                                                                                                                                                                                              | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX during self-hosted registration. Initialized with the `notset` sentinel so the OAuth client can start before the self-hosted client injects the real value at runtime. | `notset`      |
| `FLOWX_LICENSE_KEY`            | License key issued by FlowX for this self-hosted deployment.                                                                                                                                             | -             |
| `FLOWX_LICENSE_AUTHSERVERURL`  | Auth endpoint provided by FlowX licensing.                                                                                                                                                               | -             |
| `FLOWX_LICENSE_SERVERURL`      | License API endpoint provided by FlowX licensing.                                                                                                                                                        | -             |

<Warning>
  These values are provided by FlowX during the organization registration process. Without them, the License service cannot validate the platform license or report usage data.

  Your network must allow outbound connectivity to the FlowX SaaS endpoints configured above.
</Warning>

### Usage upload tuning

The License service periodically uploads usage records to FlowX SaaS. These defaults work for most deployments and only need tuning for very large organizations:

| Environment Variable                          | Description                                                         | Default Value |
| --------------------------------------------- | ------------------------------------------------------------------- | ------------- |
| `FLOWX_SCHEDULER_USAGEUPLOAD_LOADFETCHSIZE`   | Number of usage records loaded from the database per scheduler tick | `100`         |
| `FLOWX_SCHEDULER_USAGEUPLOAD_UPLOADBATCHSIZE` | Number of usage records sent per upload request to FlowX SaaS       | `500`         |

***

### Logging configuration

| Environment Variable      | Description                    | Default Value |
| ------------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_APP`       | Application-specific log level | `INFO`        |
| `LOGGING_LEVEL_LIQUIBASE` | Liquibase migration log level  | `INFO`        |

***

## Secrets management

The License service requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name                                                            | Description                     |
| ---------------------------------------------------------------------- | ------------------------------- |
| `SPRING_DATASOURCE_PASSWORD`                                           | PostgreSQL database password    |
| `SPRING_REDIS_PASSWORD`                                                | Redis authentication password   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN`                                                  | SpiceDB authentication token    |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the License service:

```yaml theme={"system"}
fullnameOverride: license

image:
  repository: <your-registry>/license

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/license
  SPRING_DATASOURCE_USERNAME: postgres

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # Security
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
  SECURITY_OAUTH2_SAREALM: 00000002-0002-4002-8002-000000000002

  # Redis
  SPRING_REDIS_HOST: redis-master

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakLicenseClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/egress-s-redis: "true"
  flowx.ai/routing-name: "license"
  flowx.ai/prometheus-scrape: "license"
```

### Network policies

The License service requires network access to the following services:

| Service    | Purpose                      | Pod Label                      |
| ---------- | ---------------------------- | ------------------------------ |
| Kafka      | Message broker communication | `flowx.ai/egress-s-kafka`      |
| PostgreSQL | Primary data storage         | `flowx.ai/egress-s-postgresql` |
| Redis      | Caching and master election  | `flowx.ai/egress-s-redis`      |
| Keycloak   | Authentication               | `flowx.ai/egress-s-keycloak`   |
| SpiceDB    | Authorization                | `flowx.ai/egress-s-spicedb`    |

***

## Monitoring

The License service exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

```yaml theme={"system"}
podLabels:
  flowx.ai/prometheus-scrape: "license"
```

### Health endpoints

| Endpoint            | Description                 |
| ------------------- | --------------------------- |
| `/actuator/health`  | Health check endpoint       |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info`    | App info endpoint           |

***

## Verify your setup

<Check>
  The License service pod is running and healthy: `kubectl get pods -l app=license`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://license:8080/actuator/health`
</Check>

<Check>
  Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`
</Check>

<Check>
  SpiceDB connection is established — check pod logs for successful CAS client initialization
</Check>

<Check>
  Kafka topics `ai.flowx.license.usage.v1` and `ai.flowx.organization.events.v1` exist and the service can consume from them
</Check>

***

## Ingress and CORS

The License service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/license`    | `/`              |

The path is set through `services.license.ingress.admin.path` (or `services.license.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                   | Default Value |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer domain that issues browser requests against License. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify the `license` database exists in PostgreSQL
    2. Check that the database user has appropriate permissions
    3. Ensure network connectivity between the pod and PostgreSQL service
    4. Verify the JDBC URL format is correct
  </Accordion>

  <Accordion title="SpiceDB connection failures">
    **Symptoms:** Authorization errors or service fails to initialize CAS client.

    **Solutions:**

    1. Verify SpiceDB is running and reachable at the configured host and port
    2. Check that the SpiceDB token is correct
    3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
    4. Review pod logs for specific CAS client error messages
  </Accordion>

  <Accordion title="Kafka consumer issues">
    **Symptoms:** License usage events or organization events not being processed.

    **Solutions:**

    1. Verify Kafka bootstrap servers are reachable
    2. Check that the `ai.flowx.license.usage.v1` and `ai.flowx.organization.events.v1` topics exist
    3. Ensure the service has consumer permissions on the topics
    4. Check consumer group offsets for lag
  </Accordion>

  <Accordion title="Service account authentication errors">
    **Symptoms:** 401/403 errors when communicating with other FlowX services.

    **Solutions:**

    1. Verify the Keycloak service account `flowx-license-sa` is properly configured
    2. Check that client secrets match between configuration and Keycloak
    3. Ensure the service account has the `view-users` client role assigned
    4. Verify the service account realm UUID is correct
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Access Management" icon="lock" href="./access-management/access-management-overview">
    Configure roles and access rights
  </Card>

  <Card title="SpiceDB Configuration" icon="shield-halved" href="./spicedb">
    Fine-grained authorization setup
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup including License service account
  </Card>
</CardGroup>


# ModPod setup
Source: https://docs.flowx.ai/5.9/setup-guides/modpod-setup

Configure the ModPod service for ML model serving with LightGBM, scikit-learn, and SHAP explainability.

ModPod is a standalone Python service. It does not depend on Kafka, Keycloak, or object storage — model artifacts and the model registry live on a local persistent volume.

***

## Dependencies

ModPod is self-contained. It does not require any other FlowX infrastructure service to run.

* **Persistent volume** — required for model artifacts and the SQLite registry
* **Identity provider** — not used; authentication is a static bearer token
* **Kafka** — not used in 5.7.0
* **Object storage (S3/MinIO)** — not used; models are stored on the mounted volume

***

## Capabilities

* Upload model packages as ZIP archives with a `metadata.json` manifest
* Manage model registry (list, fetch, delete by name/version)
* Load models into memory on demand
* Run inference with SHAP-based top-factor explanations
* Support for **LightGBM** (Booster text format) and **Logistic Regression** (scikit-learn, joblib-serialized)

***

## Authentication

ModPod uses a static bearer token. Set the `AUTHORIZATION_APIKEY` environment variable and include the token on every request except the health check:

```http theme={"system"}
Authorization: Bearer <AUTHORIZATION_APIKEY>
```

<Warning>
  The API key is a static secret. Store it in a Kubernetes `Secret` (or equivalent) and never commit it to source control.
</Warning>

***

## API endpoints

All endpoints are prefixed with `/modpod`.

### Health

| Method | Path                       | Auth | Description          |
| ------ | -------------------------- | ---- | -------------------- |
| `GET`  | `/modpod/info/healthcheck` | None | Service health check |

### Model upload

| Method | Path             | Auth   | Description                                                     |
| ------ | ---------------- | ------ | --------------------------------------------------------------- |
| `POST` | `/modpod/upload` | Bearer | Upload a ZIP archive containing model files and `metadata.json` |

The ZIP must contain a `metadata.json` file with `name` and `version` fields. Files are extracted to `<MODPOD_MODELS_DIR>/<name>/<version>/`.

### Model registry

| Method   | Path                              | Auth   | Description                     |
| -------- | --------------------------------- | ------ | ------------------------------- |
| `GET`    | `/modpod/models`                  | Bearer | List all registered models      |
| `GET`    | `/modpod/models/{name}`           | Bearer | Get model details and versions  |
| `GET`    | `/modpod/models/{name}/versions`  | Bearer | List versions for a given model |
| `DELETE` | `/modpod/models/{name}/{version}` | Bearer | Delete a specific model version |
| `DELETE` | `/modpod/models`                  | Bearer | Delete all models               |

### Inference

| Method | Path                        | Auth   | Description                      |
| ------ | --------------------------- | ------ | -------------------------------- |
| `POST` | `/modpod/inference/load`    | Bearer | Load a model into memory         |
| `POST` | `/modpod/inference/predict` | Bearer | Run prediction on a loaded model |

#### Predict request

```json theme={"system"}
{
  "model_name": "call-propensity",
  "model_version": "1.0",
  "model_type": "propensity",
  "input_data": {
    "feature1": 0.5,
    "feature2": "category_a",
    "feature3": 100
  }
}
```

#### Predict response

```json theme={"system"}
{
  "output_data": {
    "model": "call-propensity:1.0",
    "input": { "...": "..." },
    "result": {
      "prediction": 0.73,
      "top_factors": "feature1=0.50 (avg=0.30); feature2=category_a"
    }
  }
}
```

***

## Supported model types

| Type                    | Format                               | File name                      |
| ----------------------- | ------------------------------------ | ------------------------------ |
| **LightGBM**            | Booster text format                  | `encoders/model-{type}.txt`    |
| **Logistic Regression** | joblib-serialized scikit-learn model | `encoders/model-{type}.joblib` |

Both types produce SHAP-based top-factor explanations alongside the prediction. LightGBM uses the built-in `pred_contrib` output; Logistic Regression uses `shap.LinearExplainer`.

***

## Model package structure

Model packages are uploaded as ZIP archives with the following layout:

```text theme={"system"}
model.zip/
├── metadata.json
└── encoders/
    ├── model-{type}.txt         # LightGBM model (or .joblib for Logistic Regression)
    ├── {type}-feature-context.csv  # Feature metadata (mean, direction, type)
    ├── standard_scaler.pkl      # StandardScaler (Logistic Regression only)
    ├── shap_background.pkl      # SHAP background data (Logistic Regression only)
    └── {feature}-classes.pkl    # LabelEncoder per categorical feature (LightGBM)
```

The `metadata.json` file must contain at least `name` and `version`:

```json theme={"system"}
{
  "name": "call-propensity",
  "version": "1.0",
  "description": "Propensity-to-call scoring model"
}
```

***

## Environment variables

### Authentication

| Environment Variable   | Description                                           | Default Value |
| ---------------------- | ----------------------------------------------------- | ------------- |
| `AUTHORIZATION_APIKEY` | Bearer token required on all authenticated endpoints. | - (required)  |

### Storage

| Environment Variable  | Description                                                                          | Default Value         |
| --------------------- | ------------------------------------------------------------------------------------ | --------------------- |
| `MODPOD_MODELS_DIR`   | Directory where uploaded model artifacts are stored. Mount a persistent volume here. | `./models`            |
| `MODPOD_DATABASE_URL` | Database URL for the model registry. SQLite is used by default.                      | `sqlite:///modpod.db` |
| `MODPOD_DB_PATH`      | SQLite file path. Used only when `MODPOD_DATABASE_URL` is not set.                   | `./modpod.db`         |

### Server

| Environment Variable | Description                          | Default Value |
| -------------------- | ------------------------------------ | ------------- |
| `GUNICORN_WORKERS`   | Number of Gunicorn worker processes. | `1`           |
| `GUNICORN_TIMEOUT`   | Request timeout in seconds.          | `600`         |

<Info>
  Recommended worker count is `1`. Inference is CPU-bound and loaded models are held in per-process memory; additional workers multiply the memory footprint without increasing throughput for a single model.
</Info>

### CORS

| Environment Variable             | Description                                                                              | Default Value                       |
| -------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------- |
| `APPLICATION_CORS_ALLOWORIGIN`   | Comma-separated list of allowed origins. Set to the frontend origin(s) that call ModPod. | -                                   |
| `APPLICATION_CORS_ALLOW_HEADERS` | Comma-separated list of allowed request headers.                                         | Standard FlowX headers              |
| `APPLICATION_CORS_ALLOW_METHODS` | Comma-separated list of allowed HTTP methods.                                            | `GET,PUT,POST,DELETE,PATCH,OPTIONS` |

***

## Deployment

ModPod is packaged as a Docker image based on `python:3.13.3-slim-bookworm` and runs as a non-root user.

| Setting                         | Value                      |
| ------------------------------- | -------------------------- |
| Container port                  | `8080`                     |
| Health check path               | `/modpod/info/healthcheck` |
| Models directory (in container) | `/code/models`             |
| SQLite database (in container)  | `/code/modpod.db`          |

### Resource recommendations

| Resource          | Recommendation                                                     |
| ----------------- | ------------------------------------------------------------------ |
| Memory            | 512 MB – 1 GB, depending on the number and size of loaded models   |
| CPU               | 1 vCPU (inference is CPU-bound)                                    |
| Gunicorn workers  | `1`                                                                |
| Persistent volume | Minimum `5Gi` for `/code/models` (grows with the number of models) |

<Warning>
  The SQLite registry is file-based and stored on the same volume as model artifacts. To scale ModPod horizontally, switch to an external database by setting `MODPOD_DATABASE_URL` to a shared database URL.
</Warning>

***

## Validation

<Check>
  Health check returns `200 OK`:

  ```bash theme={"system"}
  curl http://<modpod-host>/modpod/info/healthcheck
  ```
</Check>

<Check>
  Authenticated listing returns an empty list (fresh install) or your registered models:

  ```bash theme={"system"}
  curl -H "Authorization: Bearer $AUTHORIZATION_APIKEY" \
    http://<modpod-host>/modpod/models
  ```
</Check>

***

## Related resources

<CardGroup>
  <Card title="Ingress configuration" icon="network-wired" href="./ingress-configuration">
    Routing and CORS for FlowX services
  </Card>

  <Card title="Setup guides overview" icon="list" href="./setup-guides-overview">
    Full list of FlowX service setup guides
  </Card>
</CardGroup>


# NoSQL DB Runner
Source: https://docs.flowx.ai/5.9/setup-guides/nosql-db-runner

Set up the NoSQL DB Runner microservice that powers FlowX Database with MongoDB and Azure Cosmos DB support.

## Configuration

The service comes with most of the needed configuration properties filled in, but there are several environment variables that need to be set up for your specific deployment.

### Database configuration

The NoSQL DB Runner connects to MongoDB for data persistence. Configure the following variables:

| Environment Variable      | Description                                   | Default Value                                                                                                                                                    |
| ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_USERNAME`             | MongoDB username for the service              | `nosql-db-runner`                                                                                                                                                |
| `DB_PASSWORD`             | MongoDB password (should be stored as secret) | `secret(mongodb-generic)`                                                                                                                                        |
| `SPRING_DATA_MONGODB_URI` | Complete MongoDB connection string            | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/nosql-db-runner` |

<Note>
  The MongoDB URI supports replica set configuration for high availability. The connection string includes multiple MongoDB instances and an arbiter for proper replica set functionality.
</Note>

### Configuring authorization & access roles

The NoSQL DB Runner validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-nosql-db-runner-sa`                                                                         |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### FlowX operations document limit

This setting allows you to configure the maximum number of documents that can be retrieved from MongoDB in a single request.

| Environment Variable                | Description                                                       | Default Value |
| ----------------------------------- | ----------------------------------------------------------------- | ------------- |
| `FLOWX_RUNOPERATIONS_DOCUMENTLIMIT` | Maximum number of documents to be processed in a single operation | `1000`        |

### External MongoDB connection caching

| Environment Variable                        | Description                                                             | Default Value |
| ------------------------------------------- | ----------------------------------------------------------------------- | ------------- |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections                   | `100`         |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL`         | Time-to-live for cached connections (duration format, e.g. `1d`, `12h`) | `1d`          |

<Tip>
  If you connect to many distinct external MongoDB instances, increase `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` to avoid frequent reconnections. Lower the TTL if your MongoDB credentials rotate frequently.
</Tip>

### Oracle Database connection pooling

| Environment Variable                            | Description                                                                  | Default Value |
| ----------------------------------------------- | ---------------------------------------------------------------------------- | ------------- |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES`      | Maximum cached JDBC connection pools                                         | `100`         |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL`              | Time-to-live for cached connection pools (duration format, e.g. `1d`, `12h`) | `1d`          |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE`              | Maximum HikariCP pool size per Oracle data source                            | `5`           |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout                                                      | `10`          |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT`                  | Default row cap on `SELECT` responses                                        | `1000`        |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS`      | Query execution timeout                                                      | `30`          |

<Tip>
  Increase `FLOWX_SQL_DEFAULTS_ROW_LIMIT` if your workflows need to read more than 1000 rows in a single query. Adjust `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` for long-running analytical queries.
</Tip>

### Configuring logging

Control log levels for different components of the service:

| Environment Variable  | Description                                   | Default Value        |
| --------------------- | --------------------------------------------- | -------------------- |
| `LOGGING_CONFIG_FILE` | Path to the logging configuration file        | `logback-spring.xml` |
| `LOGGING_LEVEL_ROOT`  | Root logger level for the Spring Boot service | `INFO`               |
| `LOGGING_LEVEL_APP`   | Application-specific log level                | `INFO`               |

<Warning>
  Using DEBUG log levels in production environments may impact performance and generate large log volumes. Consider using INFO or WARN levels for production deployments.
</Warning>

### Configuring application management

Configure management endpoints and monitoring capabilities:

| Environment Variable                                 | Description                        | Default Value          |
| ---------------------------------------------------- | ---------------------------------- | ---------------------- |
| `MANAGEMENT_SERVER_PORT`                             | Port for management endpoints      | `8081`                 |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDE`  | Health checks for liveness probes  | `ping,buildInfo`       |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE` | Health checks for readiness probes | `ping,buildInfo,mongo` |
| `MANAGEMENT_HEALTH_KUBERNETES_ENABLED`               | Enable Kubernetes health checks    | `false`                |

### Prometheus metrics configuration

Enable Prometheus metrics export for monitoring:

| Environment Variable                           | Description                      | Default Value |
| ---------------------------------------------- | -------------------------------- | ------------- |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enable Prometheus metrics export | `false`       |

<Info>
  The older form `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` also works (both resolve to the same setting). The property path above is the preferred form.
</Info>

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="MongoDB connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify MongoDB connection string format and credentials
    2. Ensure MongoDB replica set is properly configured and accessible
    3. Check network connectivity between service and MongoDB instances
    4. Verify MongoDB user permissions and database access rights
  </Accordion>

  <Accordion title="Kafka connectivity issues">
    **Symptoms:** Service cannot consume or produce Kafka messages.

    **Solutions:**

    1. Verify `SPRING_KAFKA_BOOTSTRAP_SERVERS` points to the correct broker(s)
    2. Check Kafka security protocol and authentication configuration
    3. Ensure network policies allow traffic to the Kafka cluster
    4. Verify topic names and consumer group assignments are correct
  </Accordion>

  <Accordion title="OAuth authentication errors">
    **Symptoms:** 401/403 errors when communicating with other FlowX services.

    **Solutions:**

    1. Verify OAuth client ID and client secret are correct
    2. Check OAuth server URL and realm configuration
    3. Ensure OAuth provider is accessible from the service
    4. Validate token endpoint URI configuration
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Notifications plugin setup
Source: https://docs.flowx.ai/5.9/setup-guides/notifications-plugin-setup

The Notifications plugin is available as a Docker image, and it has the following dependencies.

## Dependencies

Before setting up the plugin, ensure you have the following dependencies:

* A [MongoDB](https://www.mongodb.com/2) database for storing notification templates and records
* Access to the Kafka instance used by the FlowX.AI Engine
* A [Redis](https://redis.io/) instance for caching notification templates
* An S3-compatible file storage solution (for example [MinIO](http://min.io/)) if you need to attach documents to notifications

***

## Authorization configuration

The Notifications plugin validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| Environment Variable                                      | Description                                                           | Default Value                    |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                 |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                  |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

***

## MongoDB configuration

The only thing that needs to be configured is the DB access info, the rest will be handled by the plugin.

| Environment Variable                  | Description                                                                                                                                                   | Default Value                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI`             | MongoDB connection URI                                                                                                                                        | `mongodb://paperflow:password@jx-notification-mdb:27017/notification`                                               |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection                                                                                                                             | `true`                                                                                                              |
| `SPRING_DATA_MONGODB_RUNTIME_URI`     | Runtime MongoDB connection URI                                                                                                                                | `mongodb://${DB_USERNAME:paperflow}:${DB_PASSWORD:password}@jx-app-runtime-mdb:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME`                         | Runtime MongoDB username, referenced as a placeholder by the default runtime URI. Optional — if you override the full URI, set the credentials there instead. | `paperflow`                                                                                                         |
| `DB_PASSWORD`                         | Runtime MongoDB password, referenced as a placeholder by the default runtime URI. Optional — see `DB_USERNAME`.                                               | `password`                                                                                                          |

***

## Redis configuration

Notification Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

***

## Kafka configuration

### Core Kafka settings

| Environment Variable               | Description                                             | Default Value                  |
| ---------------------------------- | ------------------------------------------------------- | ------------------------------ |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`    | Address of the Kafka server(s)                          | `localhost:9092`               |
| `SPRING_KAFKA_SECURITY_PROTOCOL`   | Security protocol for Kafka connections                 | `PLAINTEXT`                    |
| `SPRING_KAFKA_CONSUMER_GROUPID`    | Consumer group identifier                               | `notification-plugin-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size (bytes)                            | `52428800` (50 MB)             |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10`                           |
| `KAFKA_CONSUMER_THREADS`           | Number of consumer threads                              | `1`                            |

### Consumer error handling

| Environment Variable                         | Description                                  | Default Value |
| -------------------------------------------- | -------------------------------------------- | ------------- |
| `KAFKA_CONSUMER_ERRORHANDLING_ENABLED`       | Enable consumer error handling               | `false`       |
| `KAFKA_CONSUMER_ERRORHANDLING_RETRIES`       | Number of retry attempts for failed messages | `0`           |
| `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL` | Interval between retries (milliseconds)      | `1000`        |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Topic naming configuration

| Environment Variable                      | Description                         | Default Value     |
| ----------------------------------------- | ----------------------------------- | ----------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`              | Package prefix for topic names      | `ai.flowx.`       |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT`          | Environment segment for topic names | ` `               |
| `KAFKA_TOPIC_NAMING_VERSION`              | Version suffix for topic names      | `.v1`             |
| `KAFKA_TOPIC_NAMING_SEPARATOR`            | Primary separator for topic names   | `.`               |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`           | Secondary separator for topic names | `-`               |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern              | `engine.receive.` |

### Topic configurations

Each action in the service corresponds to a Kafka event on a specific topic. Configure the following topics:

#### OTP topics

| Environment Variable           | Description                                | Default Value                                                         |
| ------------------------------ | ------------------------------------------ | --------------------------------------------------------------------- |
| `KAFKA_TOPIC_OTP_GENERATE_IN`  | Topic for incoming OTP generation requests | `ai.flowx.plugin.notification.trigger.generate.otp.v1`                |
| `KAFKA_TOPIC_OTP_GENERATE_OUT` | Topic for OTP generation results           | `ai.flowx.engine.receive.plugin.notification.generate.otp.results.v1` |
| `KAFKA_TOPIC_OTP_VALIDATE_IN`  | Topic for incoming OTP validation requests | `ai.flowx.plugin.notification.trigger.validate.otp.v1`                |
| `KAFKA_TOPIC_OTP_VALIDATE_OUT` | Topic for OTP validation results           | `ai.flowx.engine.receive.plugin.notification.validate.otp.results.v1` |

#### Notification topics

| Environment Variable                    | Description                                                                                                                                                                                                | Default Value                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN`  | Topic for incoming notification requests from the process engine (used by both Kafka-forwarded notifications and the [Send Notification action](../docs/building-blocks/actions/send-notification-action)) | `ai.flowx.plugin.notification.trigger.send.notification.v1`                |
| `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` | Topic for notification delivery confirmations                                                                                                                                                              | `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1` |
| `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` | Topic for forwarding notifications to external systems                                                                                                                                                     | `ai.flowx.plugin.notification.trigger.forward.notification.v1`             |

#### Audit topic

| Environment Variable    | Description                  | Default Value                         |
| ----------------------- | ---------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

#### Resource usages topics

| Environment Variable                                               | Description                                 | Default Value                                                                  |
| ------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------ |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH`                              | Topic for resource usages refresh events    | `ai.flowx.application-version.resources-usages.refresh.v1`                     |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_RESPONSE` | Topic for sub-resource validation responses | `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_OUT`                      | Topic for bulk resource usage operations    | `ai.flowx.application-version.resources-usages.operations.bulk.v1`             |

***

## File storage configuration

Based on use case you can use directly a file system or an S3 compatible cloud storage solution (for example [min.io](http://min.io/)).

The file storage solution can be configured using the following environment variables:

| Environment Variable                           | Description                                      | Default Value                 |
| ---------------------------------------------- | ------------------------------------------------ | ----------------------------- |
| `APPLICATION_FILESTORAGE_TYPE`                 | Storage type to use (`s3` or `fileSystem`)       | `s3`                          |
| `APPLICATION_FILESTORAGE_DISKDIRECTORY`        | Directory for file storage when using filesystem | `MS_SVC_NOTIFICATION`         |
| `APPLICATION_FILESTORAGE_S3_ENABLED`           | Enable S3-compatible storage                     | `true`                        |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`         | URL of MinIO or S3-compatible server             | `http://minio-service:9000`   |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable server-side encryption                    | `false`                       |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY`         | Access key for S3                                | `minio`                       |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY`         | Secret key for S3                                | `secret`                      |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`      | Prefix for bucket names                          | `qdevlocal-preview-paperflow` |

<Info>
  When using S3-compatible storage for notifications with attachments, the S3 user configured through `APPLICATION_FILESTORAGE_S3_ACCESSKEY` and `APPLICATION_FILESTORAGE_S3_SECRETKEY` must have read access to multiple buckets beyond its own:

  Required bucket access:

  * **Own bucket** - defined by `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
  * [**Documents Plugin bucket**](./documents-plugin-setup#general-storage-configuration) - defined in the Documents Plugin configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
  * [**CMS Core public bucket**](./cms-setup#configuring-file-storage) - defined in the CMS Core configuration via `APPLICATION_FILESTORAGE_S3_BUCKETNAME`
  * [**Integration Designer bucket**](./integration-designer-setup#storage-configuration) - defined in the Integration Designer configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`

  Ensure your S3 user has appropriate read permissions to all releva dnt buckets to avoid attachment failures.
</Info>

***

## SMTP setup

Configure SMTP settings for sending email notifications:

| Environment Variable               | Description                                                 | Default Value                |
| ---------------------------------- | ----------------------------------------------------------- | ---------------------------- |
| `SIMPLEJAVAMAIL_SMTP_HOST`         | SMTP server hostname                                        | `smtp.gmail.com`             |
| `SIMPLEJAVAMAIL_SMTP_PORT`         | SMTP server port                                            | `587`                        |
| `SIMPLEJAVAMAIL_SMTP_USERNAME`     | SMTP server username                                        | `notification.test@flowx.ai` |
| `SIMPLEJAVAMAIL_SMTP_PASSWORD`     | SMTP server password                                        | `paswword`                   |
| `SIMPLEJAVAMAIL_TRANSPORTSTRATEGY` | Email transport strategy (e.g., `SMTP`, `EXTERNAL_FORWARD`) | `SMTP`                       |
| `SIMPLEJAVAMAIL_JAVAXMAIL_DEBUG`   | Verbose JavaMail SMTP debug logging                         | `false`                      |
| `APPLICATION_MAIL_FROMEMAIL`       | Default sender email address                                | `notification.test@flowx.ai` |
| `APPLICATION_MAIL_FROMNAME`        | Default sender name                                         | `Notification`               |

### Advanced SMTP options

The notification plugin sends email through the [simple-java-mail](https://www.simplejavamail.org/) library, which auto-binds every `simplejavamail.*` property — set them as environment variables the same way as the values above. The options below come up most often when connecting to corporate SMTP relays:

| Environment Variable                           | Description                                                                                                                                                                                                  | Default Value |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `SIMPLEJAVAMAIL_DEFAULTS_VERIFYSERVERIDENTITY` | Verify that the hostname in the server's TLS certificate matches the configured SMTP host. Set to `false` for relays whose certificate doesn't match the configured hostname; the connection stays encrypted | `true`        |
| `SIMPLEJAVAMAIL_DEFAULTS_TRUSTEDHOSTS`         | Semicolon-delimited list of hosts whose TLS certificates are trusted without chain validation                                                                                                                | –             |
| `SIMPLEJAVAMAIL_DEFAULTS_TRUSTALLHOSTS`        | Accept any TLS certificate without chain validation. Prefer `SIMPLEJAVAMAIL_DEFAULTS_TRUSTEDHOSTS`                                                                                                           | `false`       |
| `SIMPLEJAVAMAIL_DEFAULTS_SESSIONTIMEOUTMILLIS` | Socket timeout (in milliseconds) for the SMTP session. Raise for slow relays                                                                                                                                 | `60000`       |

<Warning>
  These defaults load into the library's global configuration, so they apply to **all** mailers the plugin creates — including the ones built dynamically for Email Sender systems configured in the Integration Designer, whose settings override only the connection fields (host, port, username, password, transport strategy). Changing `SIMPLEJAVAMAIL_DEFAULTS_VERIFYSERVERIDENTITY` or `SIMPLEJAVAMAIL_DEFAULTS_TRUSTALLHOSTS` therefore affects every configured email system.
</Warning>

For the full list of available properties (connection pooling, embedded image resolution, and more), see the [simple-java-mail configuration reference](https://www.simplejavamail.org/configuration.html).

***

## Email attachments configuration

Configure handling of email attachments:

| Environment Variable                   | Description                                | Default Value |
| -------------------------------------- | ------------------------------------------ | ------------- |
| `SPRING_HTTP_MULTIPART_MAXFILESIZE`    | Maximum file size for attachments          | `15MB`        |
| `SPRING_HTTP_MULTIPART_MAXREQUESTSIZE` | Maximum request size for multipart uploads | `15MB`        |

***

## OTP configuration

Configure One-Time Password generation and validation:

| Environment Variable            | Description                            | Default Value        |
| ------------------------------- | -------------------------------------- | -------------------- |
| `FLOWX_OTP_LENGTH`              | Number of characters in generated OTPs | `4`                  |
| `FLOWX_OTP_EXPIRETIMEINSECONDS` | Expiry time for OTPs (seconds)         | `6000` (100 minutes) |

***

## Logging configuration

Control logging levels for different components:

| Environment Variable         | Description                               | Default Value |
| ---------------------------- | ----------------------------------------- | ------------- |
| `LOGGING_LEVEL_ROOT`         | Root logging level                        | -             |
| `LOGGING_LEVEL_APP`          | Application-specific log level            | `INFO`        |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver log level                  | `INFO`        |
| `LOGGING_LEVEL_THYMELEAF`    | Thymeleaf template engine log level       | `INFO`        |
| `LOGGING_LEVEL_FCM_CLIENT`   | Firebase Cloud Messaging client log level | `OFF`         |
| `LOGGING_LEVEL_REDIS`        | Redis/Lettuce client log level            | `OFF`         |

***

## CAS lib configuration

| Environment Variable  | Description                  | Default Value |
| --------------------- | ---------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`     |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`       |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-`           |

***

## Usage notes

### Topic naming convention

Topics follow a standardized naming convention:

* Example: `ai.flowx.plugin.notification.trigger.generate.otp.v1`
* Structure: `{package}{environment}.{component}.{action}.{subject}.{version}`

### Consumer error handling

When `KAFKA_CONSUMER_ERRORHANDLING_ENABLED` is set to `true`:

* The application will retry processing failed messages according to `KAFKA_CONSUMER_ERRORHANDLING_RETRIES`
* Between retries, the application will wait for the duration specified by `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL`

For example, if `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL` is set to 5000 (5 seconds) and `KAFKA_CONSUMER_ERROR_HANDLING_RETRIES` is set to 5, the consumer application will make up to 5 attempts, waiting 5 seconds between each attempt.

### Message size configuration

The `KAFKA_MESSAGE_MAX_BYTES` setting affects multiple Kafka properties:

* `spring.kafka.producer.properties.message.max.bytes`
* `spring.kafka.producer.properties.max.request.size`
* `spring.kafka.consumer.properties.max.partition.fetch.bytes`

### OAuth authentication

When using the 'kafka-auth' profile, the security protocol changes to 'SASL\_PLAINTEXT' and requires OAuth configuration via the `KAFKA_OAUTH_*` variables.

***

## Ingress and CORS

The Notification plugin is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path   | Backend receives |
| ---------- | --------------- | ---------------- |
| admin      | `/notification` | `/`              |

The path is set through `services.notification-plugin.ingress.admin.path` (or `services.notification-plugin.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                        | Default Value |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Notification. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Notifications not being sent">
    **Symptoms:** Notification requests are accepted but emails or messages are never delivered.

    **Solutions:**

    1. Verify Kafka topics are correctly configured and the notification plugin is consuming from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN`
    2. Check SMTP configuration (`SIMPLEJAVAMAIL_SMTP_HOST`, port, credentials) and ensure the SMTP server is reachable from the pod
    3. If using the Email Gateway for forwarding, verify `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` is configured and the Email Gateway is running
    4. Check application logs for delivery errors by setting `LOGGING_LEVEL_APP` to `DEBUG`
  </Accordion>

  <Accordion title="OTP generation fails">
    **Symptoms:** OTP requests return errors or no OTP is generated.

    **Solutions:**

    1. Verify OTP configuration values (`FLOWX_OTP_LENGTH`, `FLOWX_OTP_EXPIRETIMEINSECONDS`) are set correctly
    2. Check that Kafka topics `KAFKA_TOPIC_OTP_GENERATE_IN` and `KAFKA_TOPIC_OTP_GENERATE_OUT` are created and accessible
    3. Ensure MongoDB is reachable and the notification plugin database has write permissions
    4. Verify Kafka consumer group `SPRING_KAFKA_CONSUMER_GROUPID` is not conflicting with another instance
  </Accordion>

  <Accordion title="Notification templates not rendering">
    **Symptoms:** Notifications are sent but contain raw template syntax or missing values.

    **Solutions:**

    1. Verify substitution tags in the template match the keys provided in the notification request payload
    2. Check that the Thymeleaf engine is functioning by reviewing logs at `LOGGING_LEVEL_THYMELEAF` set to `DEBUG`
    3. Ensure the template exists in MongoDB and is in the correct format
    4. Verify Redis cache is not serving stale templates — clear the cache or restart the plugin if templates were recently updated
  </Accordion>

  <Accordion title="Firebase push notifications not working">
    **Symptoms:** Push notifications are not delivered to mobile devices.

    **Solutions:**

    1. Verify Firebase Cloud Messaging credentials are correctly configured
    2. Check that the target device has a valid FCM registration token
    3. Enable FCM client logging by setting `LOGGING_LEVEL_FCM_CLIENT` to `DEBUG` to inspect request/response details
    4. Ensure network policies allow outbound HTTPS traffic to Firebase servers (`fcm.googleapis.com`)
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Sending Notifications" icon="bell" href="../docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification">
    Learn how to configure and send notifications from your processes
  </Card>

  <Card title="Email Gateway Setup" icon="envelope-open-text" href="./email-gateway-setup">
    Configure the Email Gateway for inbound and outbound email processing
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>
</CardGroup>


# Deployment configuration for OpenTelemetry
Source: https://docs.flowx.ai/5.9/setup-guides/open-telemetry-config

Guide to deploying OpenTelemetry components and configuring associated services.

### Step 1: Install OpenTelemetry Operator

Ensure you have the OpenTelemetry Operator version **0.56.1** or higher:

```yaml theme={"system"}
    - repoURL: https://open-telemetry.github.io/opentelemetry-helm-charts
      chart: opentelemetry-operator
      targetRevision: 0.56.1
```

#### Configuration:

```yaml theme={"system"}
# Source: https://github.com/open-telemetry/opentelemetry-helm-charts/blob/opentelemetry-operator-0.56.1/charts/opentelemetry-operator/values.yaml
## Provide OpenTelemetry Operator manager container image and resources
manager:
  image:
    repository: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator
    tag: ""
  collectorImage:
    repository: "otel/opentelemetry-collector-contrib"
    tag: 0.98.0
  opampBridgeImage:
    repository: ""
    tag: ""
  targetAllocatorImage:
    repository: ""
    tag: ""
  autoInstrumentationImage:
    java:
      repository: ""
      tag: ""
    nodejs:
      repository: ""
      tag: ""
    python:
      repository: ""
      tag: ""
    dotnet:
      repository: ""
      tag: ""
    # The Go instrumentation support in the operator is disabled by default.
    # To enable it, use the operator.autoinstrumentation.go feature gate.
    go:
      repository: ""
      tag: ""
  # Feature Gates are a comma-delimited list of feature gate identifiers.
  # Prefix a gate with '-' to disable support.
  # Prefixing a gate with '+' or no prefix will enable support.
  # A full list of valid identifiers can be found here: https://github.com/open-telemetry/opentelemetry-operator/blob/main/pkg/featuregate/featuregate.go
  featureGates: ""
  ports:
    metricsPort: 8080
    webhookPort: 9443
    healthzPort: 8081
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
    requests:
      cpu: 100m
      memory: 64Mi
  ## Adds additional environment variables
  ## e.g ENV_VAR: env_value
  env:
    ENABLE_WEBHOOKS: "true"

## Admission webhooks make sure only requests with correctly formatted rules will get into the Operator.
## They also enable the sidecar injection for OpenTelemetryCollector and Instrumentation CR's
admissionWebhooks:
  create: true
  servicePort: 443
  failurePolicy: Fail
```

<Info>
  Ensure you use the appropriate distribution and version:
</Info>

```yaml theme={"system"}
    repository: "otel/opentelemetry-collector-contrib"
    tag: 0.98.0
```

### Step 2: Deploy OpenTelemetry Resources

Apply the OpenTelemetry resources:

#### OpenTelemetry Collector

```yaml theme={"system"}
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel
  namespace: {{ .Release.Namespace }}
spec:
  mode: deployment
  resources:
    limits:
      cpu: "2"
      memory: 6Gi
    requests:
      cpu: 200m
      memory: 2Gi

  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            # Since this collector needs to receive data from the web, enable cors for all origins
            # `allowed_origins` can be refined for your deployment domain
            endpoint: 0.0.0.0:4318
            cors:
              allowed_origins:
                - "http://*"
                - "https://*"
      zipkin:
    exporters:
      debug: {}
      ## Create an exporter to Jaeger using the standard `otlp` export format
      otlp/tempo:
        endpoint: 'otel-tempo:4317'
        tls:
          insecure: true
      # Create an exporter to Prometheus (metrics)
      otlphttp/prometheus:
        endpoint: 'http://otel-prometheus-server:9090/api/v1/otlp'
        tls:
          insecure: true
      loki:
        endpoint: "http://otel-loki:3100/loki/api/v1/push"
        default_labels_enabled:
          exporter: true
          job: true

    extensions:
      health_check:
      memory_ballast: {}

    processors:
      batch: {}
      k8sattributes:
        extract:
          metadata:
          - k8s.namespace.name
          - k8s.deployment.name
          - k8s.statefulset.name
          - k8s.daemonset.name
          - k8s.cronjob.name
          - k8s.job.name
          - k8s.node.name
          - k8s.pod.name
          - k8s.pod.uid
          - k8s.pod.start_time
        passthrough: false
        pod_association:
        - sources:
          - from: resource_attribute
            name: k8s.pod.ip
        - sources:
          - from: resource_attribute
            name: k8s.pod.uid
        - sources:
          - from: connection
      resource:
        attributes:
        - key: service.instance.id
          from_attribute: k8s.pod.uid
          action: insert
      memory_limiter:
        check_interval: 5s
        limit_percentage: 80
        spike_limit_percentage: 25

    connectors:
      spanmetrics: {}

    service:
      extensions:
        - health_check
        - memory_ballast
      pipelines:
        traces:
          processors: [memory_limiter, resource, batch]
          exporters: [otlp/tempo, debug, spanmetrics]
          receivers: [otlp]
        metrics:
          receivers: [otlp, spanmetrics]
          processors: [memory_limiter, resource, batch]
          exporters: [otlphttp/prometheus, debug]
        logs:
          processors: [memory_limiter, resource, batch]
          exporters: [loki, debug]
          receivers: [otlp]
```

#### OpenTelemetry Instrumentation

```yaml theme={"system"}
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: flowx-otel-instrumentation
  namespace: {{ .Release.Namespace }}
spec:
  exporter:
    endpoint: http://otel-collector:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.1.0
    env:
      - name: OTEL_INSTRUMENTATION_LOGBACKAPPENDER_ENABLED
        value: "true"
      - name: OTEL_LOGS_EXPORTER
        value: otlp
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://otelcol-operator-collector:4317
      - name: OTEL_EXPORTER_OTLP_PROTOCOL
        value: grpc
```

### Step 3: Instrument Flowx Services

Update Flowx services to enable Java instrumentation by adding the following pod annotation:

```yaml theme={"system"}
podAnnotations:
  instrumentation.opentelemetry.io/inject-java: "true"
```

### Step 4: Configure Grafana, Prometheus and Tempo

#### Configure Grafana

```yaml theme={"system"}
##Source: https://github.com/grafana/helm-charts/blob/grafana-7.3.10/charts/grafana/values.yaml
rbac:
  create: true
  namespaced: true
serviceAccount:
  create: true
replicas: 1

ingress:
  enabled: true
  ingressClassName: nginx
  path: /
  hosts:
  - {{ .Values.flowx.ingress.grafana }}

## Enable persistence using Persistent Volume Claims
## ref: http://kubernetes.io/docs/user-guide/persistent-volumes/
##
persistence:
  enabled: true
  accessModes:
    - ReadWriteOnce
  size: 5Gi
  finalizers: []

datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Loki
        uid: loki
        type: loki
        access: proxy
        url: http://otel-loki:3100
        timeout: 300
        version: 1
        jsonData:
          derivedFields:
            - datasourceUid: tempo
              # matches variations of "traceID" fields, either in JSON or logfmt
              # marian-fx: matcherRegex: '"traceid":"(\w+)"'
              matcherRegex: (?:[Tt]race[-_]?[Ii][Dd])[\\]?["]?[=:][ ]?[\\]?["]?(\w+)
              name: traceid
              # url will be interpreted as query for the datasource
              url: "$${__value.raw}"
              urlDisplayLabel: See traces

      - name: Prometheus
        uid: prometheus
        type: prometheus
        url: 'http://otel-prometheus-server:9090'
        editable: true
        isDefault: true
        jsonData:
          exemplarTraceIdDestinations:
            - datasourceUid: tempo
              name: traceid

      - name: Tempo
        uid: tempo
        type: tempo
        access: proxy
        url: http://otel-tempo:3100
        version: 1
        jsonData:
          tracesToLogs:
            datasourceUid: loki
          lokiSearch:
            datasourceUid: loki
          nodeGraph:
            enabled: true
          serviceMap:
            datasourceUid: prometheus
          tracesToLogsV2:
            customQuery: false
            datasourceUid: loki
            filterBySpanID: true
            filterByTraceID: true
            spanEndTimeShift: 1s
            spanStartTimeShift: '-1s'
            tags:
              - key: service.name
                value: job

dashboardProviders:
  dashboardproviders.yaml:
    apiVersion: 1
    providers:
      - name: 'default'
        orgId: 1
        folder: ''
        type: file
        disableDeletion: false
        editable: true
        options:
          path: /var/lib/grafana/dashboards/default

resources:
  limits:
    memory: 150Mi

grafana.ini:
  auth:
    disable_login_form: true
  auth.anonymous:
    enabled: false
    org_name: Main Org.
    org_role: Admin
  auth.generic_oauth:
    enabled: true
    name: Keycloak-OAuth
    allow_sign_up: true
    client_id: private-management-sa
    client_secret: xTs4yGYySrHaNDIpCiniHJUGqBKbyCtp
    scopes: openid email profile offline_access roles
    email_attribute_path: email
    login_attribute_path: username
    name_attribute_path: full_name
    auth_url: https://{{ .Values.flowx.keycloak.host }}/auth/realms/{{ .Values.flowx.keycloak.realm }}/protocol/openid-connect/auth
    token_url: https://{{ .Values.flowx.keycloak.host }}/auth/realms/{{ .Values.flowx.keycloak.realm }}/protocol/openid-connect/token
    api_url: https://{{ .Values.flowx.keycloak.host }}/auth/realms/{{ .Values.flowx.keycloak.realm }}/protocol/openid-connect/userinfo
    # role_attribute_path: contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
  server:
    root_url: "https://{{ .Values.flowx.ingress.grafana }}/grafana"
    serve_from_sub_path: true
adminPassword: admin

# assertNoLeakedSecrets is a helper function defined in _helpers.tpl that checks if secret
# values are not exposed in the rendered grafana.ini configmap. It is enabled by default.
#
# To pass values into grafana.ini without exposing them in a configmap, use variable expansion:
# https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#variable-expansion
#
# Alternatively, if you wish to allow secret values to be exposed in the rendered grafana.ini configmap,
# you can disable this check by setting assertNoLeakedSecrets to false.
assertNoLeakedSecrets: false
```

#### Configure Prometheus

```yaml theme={"system"}
# https://github.com/prometheus-community/helm-charts/blob/prometheus-22.6.7/charts/prometheus/values.yaml

rbac:
  create: true

podSecurityPolicy:
  enabled: false

## Define serviceAccount names for components. Defaults to component's fully qualified name.
##
serviceAccounts:
  server:
    create: true

alertmanager:
  enabled: false
alertmanagerFiles:
  alertmanager.yml:
    global: {}
      # slack_api_url: ''

    receivers:
      - name: default-receiver
        # slack_configs:
        #  - channel: '@you'
        #    send_resolved: true

    route:
      group_wait: 10s
      group_interval: 5m
      receiver: default-receiver
      repeat_interval: 3h

configmapReload:
  prometheus:
    enabled: false
kube-state-metrics:
  enabled: false
prometheus-node-exporter:
  enabled: false
prometheus-pushgateway:
  enabled: false

server:
  useExistingClusterRoleName: prometheus-server

  ## If set it will override prometheus.server.fullname value for ClusterRole and ClusterRoleBinding
  ##
  clusterRoleNameOverride: ""

  # Enable only the release namespace for monitoring. By default all namespaces are monitored.
  # If releaseNamespace and namespaces are both set a merged list will be monitored.
  releaseNamespace: false

  ## namespaces to monitor (instead of monitoring all - clusterwide). Needed if you want to run without Cluster-admin privileges.
  # namespaces:
  #   - namespace

  extraFlags:
    - "web.enable-lifecycle"
    - "enable-feature=exemplar-storage"
    - "enable-feature=otlp-write-receiver"
  global:
    scrape_interval: 5s
    scrape_timeout: 3s
    evaluation_interval: 30s
  persistentVolume:
    enabled: true
    mountPath: /data
    ## Prometheus server data Persistent Volume size
    ##
    size: 10Gi

  service:
    servicePort: 9090
  ## Prometheus server resource requests and limits
  ## Ref: http://kubernetes.io/docs/user-guide/compute-resources/
  ##
  resources:
    limits:
      cpu: 2000m
      memory: 4096Mi
    requests:
      cpu: 500m
      memory: 2048Mi
  ## Prometheus data retention period (default if not specified is 15 days)
  ##
  retention: "3d"

  ## Prometheus' data retention size. Supported units: B, KB, MB, GB, TB, PB, EB.
  ##
  retentionSize: ""

serverFiles:
  prometheus.yml:
    scrape_configs:
      - job_name: prometheus
        static_configs:
          - targets:
            - localhost:9090

      - job_name: 'otel-collector'
        honor_labels: true
        kubernetes_sd_configs:
          - role: pod
            namespaces:
              own_namespace: true
        relabel_configs:
          - source_labels: [__meta_kubernetes_pod_annotation_opentelemetry_community_demo]
            action: keep
            regex: true
```

#### Configure Loki with a Minio backend

```yaml theme={"system"}
# https://raw.githubusercontent.com/grafana/loki/helm-loki-6.2.0/production/helm/loki/single-binary-values.yaml
loki:
  auth_enabled: false # https://grafana.com/docs/loki/latest/operations/multi-tenancy/#multi-tenancy
  commonConfig:
    replication_factor: 1
  schemaConfig:
    configs:
      - from: 2024-04-01
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  ingester:
    chunk_encoding: snappy
  tracing:
    enabled: true
  querier:
    # Default is 4, if you have enough memory and CPU you can increase, reduce if OOMing
    max_concurrent: 2

deploymentMode: SingleBinary
singleBinary:
  replicas: 1
  resources:
    limits:
      cpu: 3
      memory: 4Gi
    requests:
      cpu: 1
      memory: 2Gi
  extraEnv:
    # Keep a little bit lower than memory limits
    - name: GOMEMLIMIT
      value: 3750MiB

chunksCache:
  # default is 500MB, with limited memory keep this smaller
  writebackSizeLimit: 10MB

# Enable minio for storage
minio:
  enabled: true
  rootUser: enterprise-logs
  rootPassword: supersecret
  buckets:
    - name: chunks
      policy: none
      purge: false
    - name: ruler
      policy: none
      purge: false
    - name: admin
      policy: none
      purge: false
  persistence:
    size: 10Gi

lokiCanary:
  enabled: false

# Zero out replica counts of other deployment modes
backend:
  replicas: 0
read:
  replicas: 0
write:
  replicas: 0

ingester:
  replicas: 0
querier:
  replicas: 0
queryFrontend:
  replicas: 0
queryScheduler:
  replicas: 0
distributor:
  replicas: 0
compactor:
  replicas: 0
indexGateway:
  replicas: 0
bloomCompactor:
  replicas: 0
bloomGateway:
  replicas: 0
```

#### Configure Tempo

```yaml theme={"system"}
# https://github.com/grafana/helm-charts/blob/tempo-1.7.2/charts/tempo/values.yaml

tempo:
  # configure a 3 days retention by default
  retention: 72h
  # enable opentelemetry protocol & jaeger receivers
  # this configuration will listen on all ports and protocols that tempo is capable of.
  # the receives all come from the OpenTelemetry collector.  more configuration information can
  # be found there: https://github.com/open-telemetry/opentelemetry-collector/tree/master/receiver
  receivers:
    jaeger:
      protocols:
        grpc:
          endpoint: 0.0.0.0:14250
        thrift_binary:
          endpoint: 0.0.0.0:6832
        thrift_compact:
          endpoint: 0.0.0.0:6831
        thrift_http:
          endpoint: 0.0.0.0:14268
    otlp:
      protocols:
        grpc:
          endpoint: "0.0.0.0:4317"
        http:
          endpoint: "0.0.0.0:4318"
persistence:
  enabled: true
  size: 10Gi

# -- Pod Annotations
podAnnotations:
  prometheus.io/port: prom-metrics
  prometheus.io/scrape: "true"
```


# Organization Manager setup
Source: https://docs.flowx.ai/5.9/setup-guides/organization-manager-setup

This guide provides step-by-step instructions for setting up the Organization Manager microservice.

## Dependencies

Before setting up the Organization Manager, ensure you have the following dependencies in place:

* **PostgreSQL** database for storing organization and tenant data
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization

## Infrastructure prerequisites

| Component  | Description                                           |
| ---------- | ----------------------------------------------------- |
| PostgreSQL | Dedicated database for organization data              |
| Kafka      | Message broker for inter-service communication        |
| Redis      | Caching layer for improved performance                |
| Keycloak   | Identity provider for service authentication          |
| SpiceDB    | Authorization service for fine-grained access control |

***

## Configuration

### Authorization configuration

| Environment Variable                                                                | Description                                                                                                                                                                                            | Default Value                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `SECURITY_TYPE`                                                                     | Security type (JWT public key validation)                                                                                                                                                              | `jwt-public-key`                                  |
| `SECURITY_OAUTH2_BASESERVERURL`                                                     | Base URL of the Keycloak server                                                                                                                                                                        |                                                   |
| `SECURITY_OAUTH2_SAREALM`                                                           | Service accounts realm ID                                                                                                                                                                              | `00000002-0002-4002-8002-000000000002`            |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`                  | Service account client ID                                                                                                                                                                              | `flowx-organization-manager-sa`                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`              | Service account client secret (Keycloak-issued)                                                                                                                                                        |                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`             | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)                                                  | `flowx-anonymous-sa`                              |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET`         | Anonymous service account client secret. Must be the same value across every service that uses `flowx-anonymous-sa`.                                                                                   |                                                   |
| `SECURITY_OAUTH2_REALM_ISSUERURIPATTERN`                                            | Per-organization realm URI pattern                                                                                                                                                                     | `${SECURITY_OAUTH2_BASESERVERURL}/realms/{orgId}` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                           | Organization manager URL (self-reference for security lib)                                                                                                                                             | `http://organization-manager:80`                  |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT`   | Response timeout (in seconds) for HTTP calls from organization-manager to the authorization-system service during organization provisioning. Increase if provisioning calls time out on slow networks. | `60`                                              |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for the same HTTP calls from organization-manager to the authorization-system service during organization provisioning.                                                | `30`                                              |

***

### PostgreSQL configuration

The Organization Manager uses its own dedicated PostgreSQL database.

| Environment Variable         | Description                        | Default Value                                            |
| ---------------------------- | ---------------------------------- | -------------------------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/organization_manager` |
| `SPRING_DATASOURCE_USERNAME` | Database username                  | `postgres`                                               |
| `SPRING_DATASOURCE_PASSWORD` | Database password                  | -                                                        |

<Note>
  **PostgreSQL and Redis credentials: plain env vars still work.** Organization Manager is a standard Spring Boot service — it reads the `SPRING_DATASOURCE_*` and `SPRING_DATA_REDIS_*` environment variables shown here. The `postgresql.servers/credentials` and `redis.servers/credentials` blocks in the FlowX Helm chart's `values.yaml` are the chart's own secret-to-env-var mapping; they exist to template the same plain env vars from your secrets. You can keep injecting credentials through plain environment variables exactly as before.
</Note>

<Warning>
  Ensure the database is created before deploying the service. The Organization Manager will manage its own schema migrations via Liquibase.
</Warning>

***

### Redis configuration

Organization Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

***

### Kafka configuration

#### Core Kafka settings

| Environment Variable             | Description                    | Default Value      |
| -------------------------------- | ------------------------------ | ------------------ |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092`   |
| `KAFKA_MESSAGE_MAX_BYTES`        | Maximum message size (bytes)   | `52428800` (50 MB) |

#### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

#### Kafka topics

The Organization Manager publishes organization lifecycle events:

| Environment Variable                  | Description                                                        | Default Value                     |
| ------------------------------------- | ------------------------------------------------------------------ | --------------------------------- |
| `KAFKA_TOPIC_ORGANIZATION_EVENTS_OUT` | Topic for organization lifecycle events                            | `ai.flowx.organization.events.v1` |
| `KAFKA_TOPIC_LLMCONFIG_CHANGED`       | Notifies services when LLM provider or model configuration changes | `ai.flowx.llm.config.changed.v1`  |

| Environment Variable        | Description                                                                                                          | Default Value                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys stored in the database. **Must be changed from the default in production.** | `default-dev-key-change-in-prod` |

<Warning>
  Do not use the default encryption key in production. Generate a unique key and keep it consistent across restarts — changing the key after providers are configured will make existing encrypted API keys unreadable.
</Warning>

***

### CAS lib configuration (SpiceDB)

| Environment Variable                         | Description                                                                                                                                                                             | Default Value |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`                         | SpiceDB hostname                                                                                                                                                                        | `spicedb`     |
| `FLOWX_SPICEDB_PORT`                         | SpiceDB gRPC port                                                                                                                                                                       | `50051`       |
| `FLOWX_SPICEDB_TOKEN`                        | SpiceDB authentication token                                                                                                                                                            | -             |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM`      |

***

### Organization ID configuration

The Organization ID is provided by FlowX during the organization registration process. Before starting a deployment or upgrade, this ID must be configured as an environment variable on all FlowX services that run Liquibase migrations.

<Warning>
  On self-hosted upgrades (from 5.1 or later), services will not start correctly without the Organization ID. Migration scripts require it to populate the organization ID across all database records.

  This is **not needed** for clean installations where no existing data is present in the database.
</Warning>

Set the `ORGANIZATION_ID` Liquibase parameter on the 9 services that backfill `organization_id` columns: `application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`.

```yaml theme={"system"}
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

<Warning>
  In self-hosted (non-SaaS) deployments, each of these 9 services **fails to start** if `ORGANIZATION_ID` is missing or not a valid UUID. Set it on all 9 before booting 5.9.x.
</Warning>

For the migrate-vs-fresh-install behavior across the three upgrade scenarios, see the [5.1 → 5.9 organization & deployment configuration guide](/5.9/migrating-from-5.1-lts/organization-deployment#organization_id--where-it-is-actually-required).

***

### Self-hosted URL configuration

Set the Designer and Runtime home URIs to the public URLs clients use to reach each web app. The Organization Manager uses these values to compose Keycloak redirect URIs and email links sent from the platform.

| Environment Variable                               | Description                                                                                                                                                                                                                                                                                                                                          | Default Value     |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `FLOWX_DEFAULT_DESIGNER_HOMEURI`                   | Base URL of the Designer web app. Required.                                                                                                                                                                                                                                                                                                          | -                 |
| `FLOWX_DEFAULT_RUNTIME_HOMEURI`                    | Base URL of the Runtime (generic container) web app. Required when the FlowX generic container app is deployed.                                                                                                                                                                                                                                      | -                 |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` | Comma-separated list of additional Keycloak redirect URIs. If left empty, the value is derived automatically from `FLOWX_DEFAULT_DESIGNER_HOMEURI` and `FLOWX_DEFAULT_RUNTIME_HOMEURI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]`              |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNTVERIFICATION` | Lifespan of the account verification link sent by email, in seconds.                                                                                                                                                                                                                                                                                 | `172800` (2 days) |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USERINVITE`          | Lifespan of the user invite link sent by email, in seconds.                                                                                                                                                                                                                                                                                          | `172800` (2 days) |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOTPASSWORD`      | Lifespan of the forgot-password link sent by email, in seconds.                                                                                                                                                                                                                                                                                      | `3600` (1 hour)   |

<Tip>
  In most deployments, setting `FLOWX_DEFAULT_DESIGNER_HOMEURI` (and `FLOWX_DEFAULT_RUNTIME_HOMEURI` when the generic container app is deployed) is enough — leave `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` empty and the Organization Manager will populate it for you.
</Tip>

#### Designer web app — organization code fallback

Self-hosted deployments must also set the organization code on the **Designer** web app pod. The Designer uses it as a fallback during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present.

| Environment Variable        | Description                                                                            | Default Value | Component |
| --------------------------- | -------------------------------------------------------------------------------------- | ------------- | --------- |
| `DEFAULT_ORGANIZATION_NAME` | Organization code registered with FlowX. Used by the Designer auth flow as a fallback. | -             | designer  |

<Warning>
  Leaving `DEFAULT_ORGANIZATION_NAME` unset on the Designer pod prevents authentication when users access the app at the root URL (no organization in path or subdomain).
</Warning>

***

<Info>
  **License service required.** Self-hosted deployments must also configure the [License service](/5.9/setup-guides/license-engine-setup), which connects to FlowX SaaS for license validation and usage reporting. The Organization Manager publishes organization lifecycle events via Kafka that the License service consumes.
</Info>

### Self-hosted initialization

When a self-hosted deployment starts for the first time, the Organization Manager provides endpoints for environment setup and organization registration.

#### Environment status endpoint

`GET /org/api/env` (unauthenticated)

Returns the current installation type and status:

| Status                            | Description                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `ONPREM` + `MISSING_ORGANIZATION` | Organization not yet registered. The setup screen is displayed in Designer.                            |
| `ONPREM` + `MISSING_LICENCE`      | Organization exists but the license has not been synced yet.                                           |
| `ONPREM` + `OK`                   | Fully configured. Returns organization info (org ID, issuer, token endpoint, client ID, redirect URI). |

#### Organization registration endpoint

`POST /org/api/org/single` (not available on SaaS)

Creates the self-hosted organization using a token provided by FlowX. This endpoint is called from the Designer setup screen and:

* Validates the token against the FlowX SaaS license server
* Creates the organization with the org ID and org code from the token claims
* Creates two Keycloak realms (one for users, one for service accounts)
* Creates the initial org admin user with the credentials provided in the setup screen

<Info>
  For **upgrades from 5.1**, the org admin user already exists and the setup screen is not displayed. The Organization Manager will update the existing Keycloak realm with the new organization ID.
</Info>

***

### Logging configuration

| Environment Variable | Description                    | Default Value |
| -------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT` | Root logging level             | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-specific log level | `INFO`        |

***

### Multipart upload configuration

| Environment Variable         | Description                  | Default Value |
| ---------------------------- | ---------------------------- | ------------- |
| `MULTIPART_MAX_FILE_SIZE`    | Maximum file size per upload | `50MB`        |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum total request size   | `50MB`        |

***

## Secrets management

The Organization Manager requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name                                                            | Description                     |
| ---------------------------------------------------------------------- | ------------------------------- |
| `SPRING_DATASOURCE_PASSWORD`                                           | PostgreSQL database password    |
| `SPRING_REDIS_PASSWORD`                                                | Redis authentication password   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN`                                                  | SpiceDB authentication token    |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the Organization Manager:

```yaml theme={"system"}
fullnameOverride: organization-manager

image:
  repository: <your-registry>/organization-manager

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/organization_manager
  SPRING_DATASOURCE_USERNAME: postgres

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # Security
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
  SECURITY_OAUTH2_SAREALM: 00000002-0002-4002-8002-000000000002

  # Redis
  SPRING_REDIS_HOST: redis-master

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakOrgManagerClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/routing-name: "organization-manager"
  flowx.ai/prometheus-scrape: "organization-manager"
```

### Network policies

The Organization Manager requires network access to the following services:

| Service    | Purpose                      | Pod Label                      |
| ---------- | ---------------------------- | ------------------------------ |
| Kafka      | Message broker communication | `flowx.ai/egress-s-kafka`      |
| PostgreSQL | Primary data storage         | `flowx.ai/egress-s-postgresql` |
| Redis      | Caching                      | `flowx.ai/egress-s-redis`      |
| Keycloak   | Authentication               | `flowx.ai/egress-s-keycloak`   |
| SpiceDB    | Authorization                | `flowx.ai/egress-s-spicedb`    |

***

## Monitoring

The Organization Manager exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

```yaml theme={"system"}
podLabels:
  flowx.ai/prometheus-scrape: "organization-manager"
```

### Health endpoints

| Endpoint            | Description                 |
| ------------------- | --------------------------- |
| `/actuator/health`  | Health check endpoint       |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info`    | App info endpoint           |

***

## Verify your setup

<Check>
  The Organization Manager pod is running and healthy: `kubectl get pods -l app=organization-manager`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://organization-manager:8080/actuator/health`
</Check>

<Check>
  Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`
</Check>

<Check>
  SpiceDB connection is established — check pod logs for successful CAS client initialization
</Check>

<Check>
  Kafka topic `ai.flowx.organization.events.v1` exists and the service can publish to it
</Check>

***

## Ingress and CORS

The Organization Manager service is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/org`        | `/`              |
| public     | `/org`        | `/`              |

Paths are set through `services.organization-manager.ingress.admin.path` / `services.organization-manager.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                         | Default Value |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Organization Manager. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify the `organization_manager` database exists in PostgreSQL
    2. Check that the database user has appropriate permissions
    3. Ensure network connectivity between the pod and PostgreSQL service
    4. Verify the JDBC URL format is correct
  </Accordion>

  <Accordion title="SpiceDB connection failures">
    **Symptoms:** Authorization errors or service fails to initialize CAS client.

    **Solutions:**

    1. Verify SpiceDB is running and reachable at the configured host and port
    2. Check that the SpiceDB token is correct
    3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
    4. Review pod logs for specific CAS client error messages
  </Accordion>

  <Accordion title="Kafka publishing failures">
    **Symptoms:** Organization events not reaching downstream services.

    **Solutions:**

    1. Verify Kafka bootstrap servers are reachable
    2. Check that the `ai.flowx.organization.events.v1` topic exists
    3. Ensure the service has producer permissions on the topic
    4. Review `KAFKA_MESSAGE_MAX_BYTES` if large messages fail
  </Accordion>

  <Accordion title="Service account authentication errors">
    **Symptoms:** 401/403 errors when communicating with other FlowX services.

    **Solutions:**

    1. Verify the Keycloak service account is properly configured
    2. Check that client secrets match between configuration and Keycloak
    3. Ensure the service account has required roles assigned
    4. Verify `SECURITY_TYPE` is set to `jwt-public-key`
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Access Management" icon="lock" href="./access-management/access-management-overview">
    Configure roles and access rights
  </Card>

  <Card title="SpiceDB Configuration" icon="shield-halved" href="./spicedb">
    Fine-grained authorization setup
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Open Telemetry default properties
Source: https://docs.flowx.ai/5.9/setup-guides/ot-default-properties

Default OpenTelemetry configuration properties for FlowX.AI services, including Java agent settings, exporters, and resource attributes.

* `otel.resource.attributes=service.name=flowx-process-engine,service.version=1.1.1`: Environment variable.

<Info>
  Will be overridden as environment variable by Kubernetes operator. Useful for local development.
</Info>

### Java agent configuration

* `otel.javaagent.enabled=true`
* `otel.javaagent.logging=simple`
* `otel.javaagent.debug=false`

### Disable OTEL SDK

* `otel.sdk.disabled=false`

## Exporters configuration (common config for all exporters)

* `otel.traces.exporter=otlp`
* `otel.metrics.exporter=otlp`
* `otel.logs.exporter=otlp`

### OTLP exporter

* `otel.exporter.otlp.endpoint=http://localhost:4317`

<Info>
  Endpoint will be overridden by Kubernetes operator. Useful for local development.
</Info>

* `otel.exporter.otlp.protocol=grpc`
* `otel.exporter.otlp.timeout=10000`
* `otel.exporter.otlp.compression=gzip`
* `otel.exporter.otlp.metrics.temporality.preference=cumulative`
* `otel.exporter.otlp.metrics.default.histogram.aggregation=explicit_bucket_histogram`

### Tracer provider

<Info>
  `SdkTracerProvider` specific configuration options.
</Info>

<Info>
  * Sampler: see the [OpenTelemetry sampler documentation](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#sampler)
  * The default sampler is: `parentbased_always_on`
  * To disable FlowX technical spans, add sampler: `fxTechnicalSpanFilterSampler`
</Info>

* `otel.traces.sampler=parentbased_always_on`

### Batch span processor

* `otel.bsp.schedule.delay=5000`
* `otel.bsp.max.queue.size=2048`
* `otel.bsp.max.export.batch.size=512`
* `otel.bsp.export.timeout=30000`

### Meter provider

<Info>
  The following configuration options are specific to `SdkMeterProvider`.
</Info>

* `otel.metric.export.interval=60000`
* `otel.metric.export.timeout=10000`

### Logger provider

<Info>
  The following configuration options are specific to `SdkLoggerProvider`.
</Info>

* `otel.blrp.schedule.delay=1000`
* `otel.blrp.max.queue.size=2048`
* `otel.blrp.max.export.batch.size=512`
* `otel.blrp.export.timeout=30000`

## Agent auto-instrumentation

* `otel.instrumentation.messaging.experimental.receive-telemetry.enabled=false`
* `otel.instrumentation.common.experimental.controller-telemetry.enabled=true`
* `otel.instrumentation.common.experimental.view-telemetry.enabled=true`
* `otel.instrumentation.common.default-enabled=false`

<Info>
  Disable all auto instrumentation and enable only what's necessary. This has to be commented out entirely to work as default.
</Info>

### Disable annotated methods

* `otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods=my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`

### Instrumentation config per library

<Info>
  Some instrumentation relies on other instrumentation to function properly. When selectively enabling instrumentation, be sure to enable the transitive dependencies too.
</Info>

* `otel.instrumentation.opentelemetry-api.enabled=true`
* `otel.instrumentation.opentelemetry-instrumentation-annotations.enabled=true`
* `otel.instrumentation.opentelemetry-extension-annotations.enabled=false`
* `otel.instrumentation.methods.enabled=true`
* `otel.instrumentation.external-annotations.enabled=true`
* `otel.instrumentation.kafka.enabled=true`
* `otel.instrumentation.tomcat.enabled=true`
* `otel.instrumentation.elasticsearch-transport.enabled=true`
* `otel.instrumentation.elasticsearch-rest.enabled=true`
* `otel.instrumentation.grpc.enabled=true`
* `otel.instrumentation.hibernate.enabled=false`

<Info>
  Hibernate and JDBC kind of duplicate the queries traces
</Info>

* `otel.instrumentation.hikaricp.enabled=false`

* `otel.instrumentation.java-http-client.enabled=true`

* `otel.instrumentation.http-url-connection.enabled=true`

* `otel.instrumentation.jdbc.enabled=false`

* `otel.instrumentation.jdbc-datasource.enabled=false`

* `otel.instrumentation.runtime-telemetry.enabled=true`

* `otel.instrumentation.servlet.enabled=true`

* `otel.instrumentation.executors.enabled=true`

* `otel.instrumentation.java-util-logging.enabled=true`

* `otel.instrumentation.log4j-appender.enabled=true`

* `otel.instrumentation.log4j-mdc.enabled=true`

* `otel.instrumentation.log4j-context-data.enabled=true`

* `otel.instrumentation.logback-appender.enabled=true`

* `otel.instrumentation.logback-mdc.enabled=true`

* `otel.instrumentation.mongo.enabled=true`

* `otel.instrumentation.rxjava.enabled=false`

* `otel.instrumentation.reactor.enabled=false`

### Redis client imported by spring-redis-data

* `otel.instrumentation.lettuce.enabled=true`

## Spring instrumentation props

* `otel.instrumentation.spring-batch.enabled=false`
* `otel.instrumentation.spring-core.enabled=true`
* `otel.instrumentation.spring-data.enabled=true`
* `otel.instrumentation.spring-jms.enabled=false`
* `otel.instrumentation.spring-integration.enabled=false`
* `otel.instrumentation.spring-kafka.enabled=true`
* `otel.instrumentation.spring-rabbit.enabled=false`
* `otel.instrumentation.spring-rmi.enabled=false`
* `otel.instrumentation.spring-scheduling.enabled=false`
* `otel.instrumentation.spring-web.enabled=true`
* `otel.instrumentation.spring-webflux.enabled=false`
* `otel.instrumentation.spring-webmvc.enabled=true`
* `otel.instrumentation.spring-ws.enabled=false`


# OCR plugin setup
Source: https://docs.flowx.ai/5.9/setup-guides/plugins-setup-guide/ocr-plugin-setup

The OCR plugin is a Docker image that can be deployed using the following infrastructure prerequisites.

## Infrastructure prerequisites

* S3 bucket or alternative (for example, minio)
* Kafka cluster

## Deployment/configuration

To deploy the OCR plugin, you will need to deploy `ocr-plugin` Helm chart with custom values file.

Most important sections are these, but more can be extracted from Helm chart.

```yaml theme={"system"}
image:
  repository: <repository>/ocr-plugin

applicationSecrets: {}

replicaCount: 2

resources: {}
  
env: []
```

### Kafka configuration

You can override the following environment variables:

| Environment Variable                  | Definition                                                                                                    | Default Value | Example              |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------- | -------------------- |
| `ENABLE_KAFKA_SASL`                   | Indicates whether Kafka SASL authentication is enabled                                                        | `False`       | -                    |
| `KAFKA_ADDRESS`                       | The address of the Kafka bootstrap server in the format `<hostname>:<port>`                                   | -             | `kafka-server1:9092` |
| `KAFKA_CONSUME_SCHEDULE`              | The interval (in seconds) at which Kafka messages are consumed                                                | `30`          | -                    |
| `KAFKA_INPUT_TOPIC`                   | The Kafka topic from which input messages are consumed                                                        | -             | -                    |
| `KAFKA_OCR_CONSUMER_GROUPID`          | The consumer group ID for the OCR Kafka consumer                                                              | `ocr_group`   | -                    |
| `KAFKA_CONSUMER_AUTO_COMMIT`          | Determines whether Kafka consumer commits offsets automatically                                               | `True`        | -                    |
| `KAFKA_CONSUMER_AUTO_COMMIT_INTERVAL` | The interval (in milliseconds) at which Kafka consumer commits offsets automatically                          | `1000`        | -                    |
| `KAFKA_CONSUMER_TIMEOUT`              | The timeout (in milliseconds) for Kafka consumer operations                                                   | `28000`       | -                    |
| `KAFKA_CONSUMER_MAX_POLL_INTERVAL`    | The maximum interval (in milliseconds) between consecutive polls for Kafka consume                            | `25000`       | -                    |
| `KAFKA_CONSUMER_AUTO_OFFSET_RESET`    | The strategy for resetting the offset when no initial offset is available or if the current offset is invalid | `earliest`    | -                    |
| `KAFKA_OUTPUT_TOPIC`                  | The Kafka topic to which output messages are sent                                                             | -             | -                    |

Please note that the default values and examples provided here are for illustrative purposes. Make sure to replace them with the appropriate values based on your Kafka configuration.

<Info>
  When configuring the OCR plugin, make sure to use the correct outgoing topic names that match [**the pattern expected by the Engine**](../flowx-engine-setup-guide/engine-setup#configuring-kafka), which listens for messages on topics with specific names.
</Info>

### Authorization

You can override the following environment variables:

| Environment Variable       | Definition                                             | Default Value | Example                           |
| -------------------------- | ------------------------------------------------------ | ------------- | --------------------------------- |
| `OAUTH_CLIENT_ID`          | The client ID for OAuth authentication                 | -             | `your_client_id`                  |
| `OAUTH_CLIENT_SECRET`      | The client secret for OAuth authentication             | -             | `your_client_secret`              |
| `OAUTH_TOKEN_ENDPOINT_URI` | The URI of the token endpoint for OAuth authentication | -             | `https://oauth.example.com/token` |

Please note that the default values and examples provided here are for illustrative purposes. Make sure to replace them with the appropriate values based on your OAuth authentication configuration.

### Storage (S3 configuration)

You can override the following environment variables:

| Environment Variable                | Definition                                                          | Default Value | Example                                             |
| ----------------------------------- | ------------------------------------------------------------------- | ------------- | --------------------------------------------------- |
| `STORAGE_S3_HOST`                   | The host address of the S3 storage service                          | -             | `minio:9000`, `https://s3.eu-west-1.amazonaws.com/` |
| `STORAGE_S3_SECURE_CONNECTION`      | Indicates whether to use a secure connection (HTTPS) for S3 storage | `False`       |                                                     |
| `STORAGE_S3_LOCATION`               | The location of the S3 storage service                              | -             | `eu-west-1`                                         |
| `STORAGE_S3_OCR_SCANS_BUCKET`       | The name of the S3 bucket for storing OCR scans                     | -             | `pdf-scans`                                         |
| `STORAGE_S3_OCR_SIGNATURE_BUCKET`   | The name of the S3 bucket for storing OCR signatures                | -             | `extracted-signatures`                              |
| `STORAGE_S3_OCR_SIGNATURE_FILENAME` | The filename pattern for extracted OCR signatures                   | -             | `extracted_signature_{}.png`                        |
| `STORAGE_S3_ACCESS_KEY`             | The access key for connecting to the S3 storage service             | -             |                                                     |
| `STORAGE_S3_SECRET_KEY`             | The secret key for connecting to the S3 storage service             | -             |                                                     |

Please note that the default values and examples provided here are for illustrative purposes. Make sure to replace them with the appropriate values based on your S3 storage configuration.

### Performance

| Environment Variable         | Definition                                                                                                        | Default Value |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------- |
| `ENABLE_PERFORMANCE_PAYLOAD` | When set to true, the response payload will contain performance metrics related to various stages of the process. | `true`        |

#### Example

```yaml theme={"system"}
  "perf": {
    "total_time": 998,
    "split": {
      "get_file": 248,
      "extract_images": 172,
      "extract_barcodes": 37,
      "extract_signatures": 238,
      "minio_signature_save": 301
    }
  }
```

### Certificates

You can override the following environment variables:

| Environment Variable | Definition                                                                                                  | Default Value     |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------- |
| `REQUESTS_CA_BUNDLE` | The path to the certificate bundle file used for secure requests                                            | `5`               |
| `CERT_REQUESTS`      | If no activity has occurred for a certain number of seconds, an attempt will be made to refresh the workers | `'CERT_REQUIRED'` |

### Workers behavior

You can override the following environment variables:

| Environment Variable     | Definition                                                                                                  | Default Value |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------- |
| `OCR_WORKER_COUNT`       | Number of workers                                                                                           | `5`           |
| `OCR_WORK_QUEUE_TIMEOUT` | If no activity has occurred for a certain number of seconds, an attempt will be made to refresh the workers | `10`          |

<Info>
  If no worker is released after `OCR_WORK_QUEUE_TIMEOUT` seconds, the application will verify whether any workers have become unresponsive and need to be restarted.

  If none of the workers have died, it means they are likely blocked in some process. In this case, the application will terminate all the workers and shut down itself, hoping that the container will be restarted.
</Info>

### Control aspect ratio

| Environment Variable      | Definition                                                                                                                                                                                                                  | Default Value |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `OCR_SIGNATURE_MAX_RATIO` | This variable sets the maximum acceptable aspect ratio for a signed scanned document (the OCR plugin will recognize a signature only if the document aspect ratio is less than or equal to the specified maximum ratio)     | `1.43`        |
| `OCR_SIGNATURE_MIN_RATIO` | This variable sets the minimum acceptable aspect ratio for a signed scanned document (the OCR plugin will consider a detected signature only if the document ratio is greater than or equal to the specified minimum ratio) | `1.39`        |

<Info>
  The plugin has been tested with aspect ratio values between 1.39 and 1.43. However, caution is advised when using untested values outside this range, as they may potentially disrupt the functionality. Adjust these parameters at your own risk and consider potential consequences, as untested values might lead to plugin instability or undesired behavior.
</Info>


# Plugins setup
Source: https://docs.flowx.ai/5.9/setup-guides/plugins-setup-guide/plugins-setup-guide-overview

To set up a plugin in your environment, you must go through the next steps.

* make sure you have all the prerequisites deployed on your environment (for example a [Redis](../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis) cache instance, a DB instance, etc)
* make the necessary configurations for each plugin (DB connection data, related Kafka topic names, etc)

Once you have deployed the necessary plugins in your environment, you can start integrating them in your process definitions.

All of them listen for Kafka events sent by the **FlowX Engine** and perform certain actions depending on the received data. They can also send data back to the Engine.

Some of them require some custom templates to be configured, for these cases, a [WYSIWYG Editor](../../docs/platform-deep-dive/plugins/wysiwyg) is provided.

Let's go into more details on setting up and using each of them:

<CardGroup>
  <Card title="OCR plugin" href="ocr-plugin-setup" icon="file-magnifying-glass" />

  <Card title="Reporting" href="reporting-setup" icon="chart-simple" />
</CardGroup>


# Reporting setup
Source: https://docs.flowx.ai/5.9/setup-guides/plugins-setup-guide/reporting-setup

The Reporting setup guide assists in configuring the reporting plugin, relying on specific dependencies and configurations.

The FlowX Reporting solution provides data analytics and visualization capabilities for your FlowX platform. This guide offers step-by-step instructions for setting up and configuring all components of the reporting system.

The reporting solution consists of three main components:

* **Reporting Plugin**: Extracts and processes data from the FlowX Engine
* **Spark Application**: Handles data transformation and loading operations
* **Apache Superset**: Provides the visualization interface and dashboard capabilities

## Dependencies

The reporting plugin, available as a Docker image, requires the following dependencies:

* **PostgreSQL**: Dedicated instance for reporting data storage.
* **Reporting-plugin Helm Chart**:
  * Utilizes a Spark Application to extract data from the FLOWX.AI Engine database and populate the Reporting plugin database.
  * Utilizes Spark Operator. For more information, see the [Spark Operator documentation](https://www.kubeflow.org/docs/components/spark-operator).
* **Superset**:
  * Requires a dedicated PostgreSQL database for its operation.
  * Utilizes Redis for efficient caching.
  * Exposes its user interface via an ingress.

## Prerequisites

Before starting the installation, ensure you have:

* Kubernetes cluster with Helm installed
* Access to PostgreSQL databases for:
  * FlowX Engine database (source)
  * Reporting database (destination)
  * Superset metadata database
* Docker registry access for the reporting images
* Redis instance for Superset caching
* Ingress controller for exposing Superset UI

## Reporting plugin helm chart configuration

Configuring the reporting plugin involves several steps:

### Installation of Spark Operator

1. Install the Spark Operator using Helm:

```bash theme={"system"}
helm install local-spark-release spark-operator/spark-operator \
--namespace spark-operator --create-namespace \
--set webhook.enable=true \
--set logLevel=6
```

2. Apply RBAC configurations:

```bash theme={"system"}
kubectl apply -f spark-rbac.yaml
```

3. Build the reporting image:

```bash theme={"system"}
docker build ...
```

4. Update the `reporting-image` URL in the `spark-app.yml` file.

5. Configure the correct database ENV variables in the `spark-app.yml` file (check them in the above examples with/without webhook).

6. Deploy the application:

```bash theme={"system"}
kubectl apply -f operator/spark-app.yaml
```

## Spark Operator deployment options

### Without webhook

For deployments without a webhook, manage secrets and environmental variables for security:

```yaml theme={"system"}
sparkApplication: #Defines the Spark application configuration.
  enabled: "true" #Indicates that the Spark application is enabled for deployment.
  schedule: "@every 5m" #A cronJob that should run at every 5 minutes.
  driver: # This section configures the driver component of the Spark application.
    envVars: #Environment variables for driver setup.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      APPLICATION_DATABASE_USER: postgres
      APPLICATION_DATABASE_URL: localhost:5439
      APPLICATION_DATABASE_NAME: app_manager
      APPLICATION_DATABASE_TYPE: postgres
      ENGINE_DATABASE_PASSWORD: "password"
      REPORTING_DATABASE_PASSWORD: "password"
      APPLICATION_DATABASE_PASSWORD: "password"

  executor: #This section configures the executor component of the Spark application.
    envVars: #Environment variables for executor setup.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      APPLICATION_DATABASE_USER: postgres
      APPLICATION_DATABASE_URL: localhost:5439
      APPLICATION_DATABASE_NAME: app_manager
      APPLICATION_DATABASE_TYPE: postgres
      ENGINE_DATABASE_PASSWORD: "password"
      REPORTING_DATABASE_PASSWORD: "password"
      APPLICATION_DATABASE_PASSWORD: "password"
      
```

<Info>
  NOTE: Passwords are currently set as plain strings, which is not secure practice in a production environment.
</Info>

### With webhook

When using the webhook, employ environmental variables with secrets for a balanced security approach:

```yaml theme={"system"}
sparkApplication:
  enabled: "true"
  schedule: "@every 5m"
  driver:
    env: #Environment variables for driver setup with secrets.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle     
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      APPLICATION_DATABASE_USER: postgres
      APPLICATION_DATABASE_URL: localhost:5439
      APPLICATION_DATABASE_NAME: app_manager
      APPLICATION_DATABASE_TYPE: postgres
    extraEnvVarsMultipleSecretsCustomKeys: 
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
          APPLICATION_DATABASE_PASSWORD: postgresql-password
  executor:
    env: #Environment variables for executor setup with secrets.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      APPLICATION_DATABASE_USER: postgres
      APPLICATION_DATABASE_URL: localhost:5439
      APPLICATION_DATABASE_NAME: app_manager
      APPLICATION_DATABASE_TYPE: postgres
    extraEnvVarsMultipleSecretsCustomKeys:
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
          APPLICATION_DATABASE_PASSWORD: postgresql-password
```

<Info>
  In Kubernetes-based Spark deployments managed by the Spark Operator, you can define the sparkApplication configuration to customize the behavior, resources, and environment for both the driver and executor components of Spark jobs. The driver section allows fine-tuning of parameters specifically pertinent to the driver part of the Spark application.
</Info>

Below are the configurable values within the chart values.yml file (with webhook):

```yml theme={"system"}
apiVersion: "sparkoperator.k8s.io/v1beta2"
kind: ScheduledSparkApplication
metadata:
  name: reporting-plugin-spark-app
  namespace: dev
  labels:
    app.kubernetes.io/component: reporting
    app.kubernetes.io/instance: reporting-plugin
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: reporting-plugin
    app.kubernetes.io/release: 0.0.1-FLOWXRELEASE
    app.kubernetes.io/version: 0.0.1-FLOWXVERSION
    helm.sh/chart: reporting-plugin-0.2.4
spec:
  schedule: '@every 5m'
  concurrencyPolicy: Forbid
  template:
    type: Python
    pythonVersion: "3"
    mode: cluster
    image: <your-registry>/reporting-plugin:0.2.4
    imagePullPolicy: IfNotPresent
    mainApplicationFile: local:///opt/spark/work-dir/main.py
    sparkVersion: "3.1.1"
    restartPolicy:
      type: Never
      onFailureRetries: 0
      onFailureRetryInterval: 10
      onSubmissionFailureRetries: 5
      onSubmissionFailureRetryInterval: 20
    driver:
      cores: 1
      coreLimit: 1200m
      memory: 512m
      labels:
        version: 3.1.1
      serviceAccount: spark
      env:
        ENGINE_DATABASE_USER: flowx
        ENGINE_DATABASE_URL: postgresql:5432
        ENGINE_DATABASE_NAME: process_engine
        ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
        REPORTING_DATABASE_USER: flowx
        REPORTING_DATABASE_URL: postgresql:5432
        REPORTING_DATABASE_NAME: reporting
        REPORTING_DATABASE_TYPE: postgres
        APPLICATION_DATABASE_USER: postgres
        APPLICATION_DATABASE_URL: localhost:5439
        APPLICATION_DATABASE_NAME: app_manager
        APPLICATION_DATABASE_TYPE: postgres
        ENGINE_DATABASE_PASSWORD: "password"
        REPORTING_DATABASE_PASSWORD: "password"
        APPLICATION_DATABASE_PASSWORD: "password"
    extraEnvVarsMultipleSecretsCustomKeys: 
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
          APPLICATION_DATABASE_PASSWORD: postgresql-password
    executor:
      cores:  1
      instances: 3
      memory: 512m
      labels:
        version: 3.1.1
      env: #Environment variables for executor setup with secrets.
        ENGINE_DATABASE_USER: flowx
        ENGINE_DATABASE_URL: postgresql:5432
        ENGINE_DATABASE_NAME: process_engine
        ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
        REPORTING_DATABASE_USER: flowx
        REPORTING_DATABASE_URL: postgresql:5432
        REPORTING_DATABASE_NAME: reporting
        REPORTING_DATABASE_TYPE: postgres
        APPLICATION_DATABASE_USER: postgres
        APPLICATION_DATABASE_URL: localhost:5439
        APPLICATION_DATABASE_NAME: app_manager
        APPLICATION_DATABASE_TYPE: postgres
    extraEnvVarsMultipleSecretsCustomKeys:
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
          APPLICATION_DATABASE_PASSWORD: postgresql-password
```

### Superset configuration

Detailed Superset Configuration Guide:

<Card title="Superset configuration" href="https://github.com/apache/superset/blob/master/helm/superset/README.md" icon="link" />

<Card title="Superset docker image" href="https://hub.docker.com/r/apache/superset" icon="link" />

Refer to Superset Documentation for in-depth information:

<Card title="Superset documentation" href="https://superset.apache.org/docs/intro/" icon="link" />

## Post-installation steps

After installation, perform the following essential configurations:

### Datasource configuration

For document-related data storage, configure these environment variables:

* `SPRING_DATASOURCE_URL`
* `SPRING_DATASOURCE_USERNAME`
* `SPRING_DATASOURCE_PASSWORD`

Ensure accurate details to prevent startup errors. The Liquibase script manages schema and migrations.

### Redis configuration

The following values should be set with the corresponding Redis-related values:

* `SPRING_REDIS_HOST`
* `SPRING_REDIS_PORT`

## Keycloak configuration

To implement alternative user authentication:

* Override `AUTH_TYPE` in your `superset.yml` configuration file:
  * Set `AUTH_TYPE: AUTH_OID`
* Provide the reference to your `openid-connect` realm:
  * `OIDC_OPENID_REALM: 'flowx'`

With this configuration, the login page changes to a prompt where the user can select the desired OpenID provider.

### Extend the security manager

Firstly, you will want to make sure that flask stops using `flask-openid` and starts using `flask-oidc` instead.

To do so, you will need to create your own security manager that configures `flask-oidc` as its authentication provider.

```yml theme={"system"}
extraSecrets:
  keycloak_security_manager.py: |
    from flask_appbuilder.security.manager import AUTH_OID
    from superset.security import SupersetSecurityManager
    from flask_oidc import OpenIDConnect
```

To enable OpenID in Superset, you would previously have had to set the authentication type to `AUTH_OID`.

The security manager still executes all the behavior of the super class, but overrides the OID attribute with the `OpenIDConnect` object.

Further, it replaces the default OpenID authentication view with a custom one:

```yml theme={"system"}
    from flask_appbuilder.security.views import AuthOIDView
    from flask_login import login_user
    from urllib.parse import quote
    from flask_appbuilder.views import expose
    from flask import request, redirect

    class AuthOIDCView(AuthOIDView):
        @expose('/login/', methods=['GET', 'POST'])
        def login(self, flag=True):
            sm = self.appbuilder.sm
            oidc = sm.oid
            superset_roles = ["Admin", "Alpha", "Gamma", "Public", "granter", "sql_lab"]
            default_role = "Admin"
            @self.appbuilder.sm.oid.require_login
            def handle_login():
                user = sm.auth_user_oid(oidc.user_getfield('email'))
                if user is None:
                    info = oidc.user_getinfo(['preferred_username', 'given_name', 'family_name', 'email', 'roles'])
                    roles = [role for role in superset_roles if role in info.get('roles', [])]
                    roles += [default_role, ] if not roles else []
                    user = sm.add_user(info.get('preferred_username'), info.get('given_name', ''), info.get('family_name', ''),
                                       info.get('email'), [sm.find_role(role) for role in roles])
                login_user(user, remember=False)
                return redirect(self.appbuilder.get_url_for_index)
            return handle_login()
        @expose('/logout/', methods=['GET', 'POST'])
        def logout(self):
            oidc = self.appbuilder.sm.oid
            oidc.logout()
            super(AuthOIDCView, self).logout()
            redirect_url = request.url_root.strip('/')
            # redirect_url = request.url_root.strip('/') + self.appbuilder.get_url_for_login
            return redirect(
                oidc.client_secrets.get('issuer') + '/protocol/openid-connect/logout?redirect_uri=' + quote(redirect_url))
```

On authentication, the user is redirected back to Superset.

### Configure Superset authentication

Finally, we need to add some parameters to the superset .yml file:

```yml theme={"system"}
    '''
    ---------------------------KEYCLOACK ----------------------------
    '''
    curr  =  os.path.abspath(os.getcwd())
    AUTH_TYPE = AUTH_OID
    OIDC_CLIENT_SECRETS =  curr + '/pythonpath/client_secret.json'
    OIDC_ID_TOKEN_COOKIE_SECURE = True
    OIDC_REQUIRE_VERIFIED_EMAIL = True
    OIDC_OPENID_REALM: 'flowx'
    OIDC_INTROSPECTION_AUTH_METHOD: 'client_secret_post'
    CUSTOM_SECURITY_MANAGER = OIDCSecurityManager
    AUTH_USER_REGISTRATION = False
    AUTH_USER_REGISTRATION_ROLE = 'Admin'
    OVERWRITE_REDIRECT_URI = 'https://{{ .Values.flowx.ingress.reporting }}/oidc_callback'
    '''
    --------------------------------------------------------------
    '''
```


# Scheduler setup
Source: https://docs.flowx.ai/5.9/setup-guides/scheduler-setup-guide

This guide will walk you through the process of setting up the Scheduler service.

## Infrastructure prerequisites

* **MongoDB**
* **Kafka**
* **OpenID Connect Settings**

***

## Dependencies

* [MongoDB](https://www.mongodb.com/2) database
* Ability to connect to a Kafka instance used by the FlowX Engine
* Scheduler service account - required for using Start Timer event node. For more information, see the [scheduler service account configuration](./access-management/configuring-an-iam-solution#scheduler-service-account).

The service comes with most of the required configuration properties pre-filled. However, certain custom environment variables need to be set up.

<Warning>
  This service needs to connect to a Mongo database that has replicas to work correctly.
</Warning>

***

## Scheduler configuration

### Scheduler

```yaml theme={"system"}
scheduler:
  thread-count: 30  # Configure the number of threads to be used for sending expired messages.
  callbacks-thread-count: 60 # Configure the number of threads for handling Kafka responses, whether the message was successfully sent or not
  cronExpression: "*/10 * * * * *" #every 10 seconds
  retry: # new retry mechanism
    max-attempts: 3
    seconds: 1
    thread-count: 3
    cronExpression: "*/10 * * * * *" #every 10 seconds
  cleanup:
    cronExpression: "*/25 * * * * *" #every 25 seconds
```

* `SCHEDULER_THREAD_COUNT`: Used to configure the number of threads to be used for sending expired.
* `SCHEDULER_CALLBACKS_THREAD_COUNT`: Used to configure the number of threads for handling Kafka responses, whether the message was successfully sent or not.

<Info>
  The "scheduler.cleanup.cronExpression" is valid for both scheduler and timer event scheduler.
</Info>

#### Retry mechanism

* `SCHEDULER_RETRY_THREAD_COUNT`: Specify the number of threads to use for resending messages that need to be retried.
* `SCHEDULER_RETRY_MAX_ATTEMPTS`: This configuration parameter sets the number of retry attempts. For instance, if it's set to 3, it means that the system will make a maximum of three retry attempts for message resending.
* `SCHEDULER_RETRY_SECONDS`: This configuration parameter defines the time interval, in seconds, for retry attempts. For example, when set to 1, it indicates that the system will retry the operation after a one-second delay.

#### Cleanup

* `SCHEDULER_CLEANUP_CRONEXPRESSION`: It specifies how often, in seconds, events that have already been processed should be cleaned up from the database.

#### Recovery mechanism

```yaml theme={"system"}
flowx:
  timer-calculator:
    delay-max-repetitions: 1000000
```

<Tip>
  You have a "next execution" set for 10:25, and the cycle step is 10 minutes. If the instance goes down for 2 hours, the next execution time should be 12:25, not 10:35. To calculate this, you add 10 minutes repeatedly to 10:25 until you reach the current time. So, it would be 10:25 + 10 min + 10 min + 10 min, until you reach the current time of 12:25. This ensures that the next execution time is adjusted correctly after the downtime.
</Tip>

* `FLOWX_TIMER_CALCULATOR_DELAY_MAX_REPETITIONS`: This means that, for example, if our cycle step is set to one second and the system experiences a downtime of two weeks, which is equivalent to 1,209,600 seconds, and we have the "max repetitions" set to 1,000,000, it will attempt to calculate the next schedule. However, when it reaches the maximum repetitions, an exception is thrown, making it impossible to calculate the next schedule. As a result, the entry remains locked and needs to be rescheduled. This scenario represents a critical case where the system experiences extended downtime, and the cycle step is very short (e.g., 1 second), leading to the inability to determine the next scheduled event.

### Timer event scheduler

<Info>
  Configuration for Timer Event scheduler designed to manage timer events. Similar configuration to scheduler.
</Info>

```yaml theme={"system"}
timer-event-scheduler:
  thread-count: 30
  callbacks-thread-count: 60
  cronExpression: "*/1 * * * * *" #every 1 seconds
  retry:
    max-attempts: 3
    seconds: 1
    thread-count: 3
    cronExpression: "*/5 * * * * *" #every 5 seconds
```

***

## OpenID connect settings

| Environment variable                                                        | Description                                                                                                                                           | Default value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SECURITY_PATHAUTHORIZATIONS_0_PATH`                                        | Security path pattern                                                                                                                                 | `/api/**`                                                                                          |
| `SECURITY_PATHAUTHORIZATIONS_0_ROLESALLOWED`                                | Roles allowed for path access                                                                                                                         | `ANY_AUTHENTICATED_USER`                                                                           |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-scheduler-core-sa`                                                                          |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

<Info>
  When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.
</Info>

The service account is essential for enabling the [**Start Timer**](../docs/building-blocks/node/timer-events/timer-start-event) event node.

More details about the necessary service account, here:

[Scheduler service account](./access-management/configuring-an-iam-solution#scheduler-service-account)

***

## Configuring datasoruce (MongoDB)

The MongoDB database is used to persist scheduled messages until they are sent back. The following configurations need to be set using environment variables:

* `SPRING_DATA_MONGODB_URI`: The URI for the MongoDB database.

***

## Configuring Kafka

### Core Kafka settings

| Environment Variable               | Description                                                                          | Default Value        |
| ---------------------------------- | ------------------------------------------------------------------------------------ | -------------------- |
| `KAFKA_BOOTSTRAP_SERVERS`          | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)                  | `localhost:9092`     |
| `KAFKA_SECURITY_PROTOCOL`          | Security protocol for Kafka connections (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT`          |
| `SPRING_KAFKA_CONSUMER_GROUPID`    | Consumer group identifier                                                            | `scheduler-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES`          | Maximum message size (bytes)                                                         | `52428800` (50 MB)   |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds)                              | `10`                 |

### Consumer configuration

| Environment Variable                              | Description                                 | Default Value                 |
| ------------------------------------------------- | ------------------------------------------- | ----------------------------- |
| `KAFKA_CONSUMER_THREADS`                          | Number of Kafka consumer threads            | `1`                           |
| `KAFKA_CONSUMER_SCHEDULEDTIMEREVENTS_THREADS`     | Number of threads for starting Timer Events | `1`                           |
| `KAFKA_CONSUMER_SCHEDULEDTIMEREVENTS_GROUPID`     | Consumer group for starting timer events    | `scheduled-timer-events`      |
| `KAFKA_CONSUMER_STOPSCHEDULEDTIMEREVENTS_THREADS` | Number of threads for stopping Timer Events | `1`                           |
| `KAFKA_CONSUMER_STOPSCHEDULEDTIMEREVENTS_GROUPID` | Consumer group for stopping timer events    | `stop-scheduled-timer-events` |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

### Kafka topics

#### Schedule topics

| Environment Variable           | Description                                      | Default Value                            |
| ------------------------------ | ------------------------------------------------ | ---------------------------------------- |
| `KAFKA_TOPIC_SCHEDULE_IN_SET`  | Receives scheduled message setting requests      | `ai.flowx.core.trigger.set.schedule.v1`  |
| `KAFKA_TOPIC_SCHEDULE_IN_STOP` | Handles requests to terminate scheduled messages | `ai.flowx.core.trigger.stop.schedule.v1` |

#### Timer events topics

| Environment Variable                       | Description                     | Default Value                                        |
| ------------------------------------------ | ------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_SET`  | Topic for setting timer events  | `ai.flowx.core.trigger.set.timer-event-schedule.v1`  |
| `KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_STOP` | Topic for stopping timer events | `ai.flowx.core.trigger.stop.timer-event-schedule.v1` |

<Info>
  Make sure the topics configured for this service don't follow the engine pattern.
</Info>

***

## Configuring logging

The following environment variables can be set to control log levels:

* `LOGGING_LEVEL_ROOT`: Root Spring Boot microservice logs (Default: `INFO`)
* `LOGGING_LEVEL_APP`: App level logs (Default: `INFO`)

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Scheduled processes not triggering">
    **Symptoms:** Scheduled processes do not start at the expected times.

    **Solutions:**

    1. Verify the cron expressions in `SCHEDULER_CLEANUP_CRONEXPRESSION` and the scheduler `cronExpression` settings are correct
    2. Check that Kafka topics (`KAFKA_TOPIC_SCHEDULE_IN_SET`, `KAFKA_TOPIC_SCHEDULE_IN_STOP`) are correctly configured and accessible
    3. Confirm the scheduler service is healthy by checking `/actuator/health`
    4. Review scheduler logs at `DEBUG` level for missed or skipped executions
  </Accordion>

  <Accordion title="Duplicate schedule executions">
    **Symptoms:** Scheduled messages are sent multiple times for the same event.

    **Solutions:**

    1. Check the replica count — running multiple replicas without proper leader election can cause duplicates
    2. Verify that the MongoDB replica set is healthy, as the scheduler relies on it for distributed locking
    3. Review `SCHEDULER_THREAD_COUNT` and `SCHEDULER_CALLBACKS_THREAD_COUNT` to ensure they are not excessively high for your workload
  </Accordion>

  <Accordion title="Scheduler fails to start">
    **Symptoms:** The scheduler service crashes or fails during startup.

    **Solutions:**

    1. Verify MongoDB connectivity and ensure the database has replicas enabled (required for the scheduler to work correctly)
    2. Check that Kafka bootstrap servers are reachable (`KAFKA_BOOTSTRAP_SERVERS`)
    3. Confirm the service account credentials are valid — verify `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` and `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`
    4. Review startup logs for specific connection error messages
  </Accordion>

  <Accordion title="Timer events not firing">
    **Symptoms:** Timer event nodes in processes do not trigger at the configured times.

    **Solutions:**

    1. Verify the timer event configuration in the process definition (Start Timer, Intermediate Timer)
    2. Check that the timer event Kafka topics are correctly set (`KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_SET`, `KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_STOP`)
    3. Ensure the scheduler service account has the necessary permissions — see the [Scheduler service account](./access-management/configuring-an-iam-solution#scheduler-service-account) configuration
    4. Review the `FLOWX_TIMER_CALCULATOR_DELAY_MAX_REPETITIONS` setting if the system experienced recent downtime
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Scheduled Processes" icon="clock" href="../docs/projects/runtime/scheduled-processes">
    Configure and manage scheduled process executions
  </Card>

  <Card title="Timer Events" icon="timer" href="../docs/building-blocks/node/timer-events/timer-events">
    Timer event node types and configuration options
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>
</CardGroup>


# FlowX Data Search setup
Source: https://docs.flowx.ai/5.9/setup-guides/search-data-service-setup-guide

Comprehensive guide for installing, configuring, and deploying the FlowX Data Search service

The FlowX Data Search service enables searching capabilities across your FlowX platform. This guide provides detailed instructions for setting up, configuring, and deploying the service in your environment.

***

## Infrastructure prerequisites

The FlowX Data Search service requires the following infrastructure components:

| Component         | Purpose                                     |
| ----------------- | ------------------------------------------- |
| **Redis**         | Caching search results and configurations   |
| **Kafka**         | Message-based communication with the engine |
| **Elasticsearch** | Indexing and searching data                 |

***

## Configuration

### Kafka configuration

Configure Kafka communication using these environment variables and properties:

#### Basic Kafka settings

| Variable                  | Description                                                              | Default Value      |
| ------------------------- | ------------------------------------------------------------------------ | ------------------ |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)      | `localhost:9092`   |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT`        |
| `KAFKA_CONSUMER_THREADS`  | Number of Kafka consumer threads                                         | `1`                |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size                                                     | `52428800` (50 MB) |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Topic naming configuration

The Data Search service uses a structured topic naming convention:

```
{package}{environment}.{component}.{action}.{version}
```

For example: `ai.flowx.core.trigger.search.data.v1`

| Variable                                  | Description                         | Default Value     |
| ----------------------------------------- | ----------------------------------- | ----------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`              | Package prefix for topic names      | `ai.flowx.`       |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT`          | Environment segment for topic names | ` `               |
| `KAFKA_TOPIC_NAMING_VERSION`              | Version suffix for topic names      | `.v1`             |
| `KAFKA_TOPIC_NAMING_SEPARATOR`            | Primary separator for topic naming  | `.`               |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`           | Secondary separator                 | `-`               |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern              | `engine.receive.` |

#### Kafka topics

The service uses these specific topics:

| Topic                         | Default Value                                         | Purpose                  |
| ----------------------------- | ----------------------------------------------------- | ------------------------ |
| `KAFKA_TOPIC_DATA_SEARCH_IN`  | `ai.flowx.core.trigger.search.data.v1`                | Incoming search requests |
| `KAFKA_TOPIC_DATA_SEARCH_OUT` | `ai.flowx.engine.receive.core.search.data.results.v1` | Outgoing search results  |

### Elasticsearch configuration

Configure Elasticsearch connection using the following environment variables:

| Variable                                  | Description                                 | Default Value      | Default Value        |
| ----------------------------------------- | ------------------------------------------- | ------------------ | -------------------- |
| `SPRING_ELASTICSEARCH_REST_URIS`          | URL(s) of Elasticsearch nodes (no protocol) | -                  | `elasticsearch:9200` |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL`      | Connection protocol                         | `https`            | `https` or `http`    |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL`    | Disable SSL verification                    | `false`            | `false`              |
| `SPRING_ELASTICSEARCH_REST_USERNAME`      | Authentication username                     | -                  | `elastic`            |
| `SPRING_ELASTICSEARCH_REST_PASSWORD`      | Authentication password                     | -                  | `your-password`      |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | Index name for search data                  | `process_instance` | `process_instance`   |

### Security configuration

The Search Data service validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| Variable                                                  | Description                                                           | Default Value                    |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                 |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                  |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### Logging configuration

Control the verbosity of logs with these variables:

| Variable             | Description                    | Default Value |
| -------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot log level     | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-specific log level | `INFO`        |

***

## Elasticsearch index configuration

The Data Search service creates and manages Elasticsearch indices based on the configured index pattern. The default index name is `process_instance`.

### Index pattern

The service derives the index pattern from the `spring.elasticsearch.index-settings.name` property. This pattern is used to query across multiple indices that match the pattern.

### Sample search query

Below is an example of a search query generated by the Data Search service for Elasticsearch:

```json theme={"system"}
{
  "query": {
    "bool": {
      "adjust_pure_negative": true,
      "boost": 1,
      "must": [
        {
          "nested": {
            "boost": 1,
            "ignore_unmapped": false,
            "path": "keyIdentifiers",
            "query": {
              "bool": {
                "adjust_pure_negative": true,
                "boost": 1,
                "must": [
                  {
                    "match": {
                      "keyIdentifiers.key.keyword": {
                        "query": "astonishingAttribute",
                        "operator": "OR"
                      }
                    }
                  },
                  {
                    "match": {
                      "keyIdentifiers.originalValue.keyword": {
                        "query": "OriginalGangsta",
                        "operator": "OR"
                      }
                    }
                  }
                ]
              }
            },
            "score_mode": "none"
          }
        },
        {
          "terms": {
            "boost": 1,
            "processDefinitionName.keyword": [
              "TEST_PORCESS_NAME_0",
              "TEST_PORCESS_NAME_1"
            ]
          }
        }
      ]
    }
  }
}
```

***

## Integration with Kibana

Kibana provides an interface for visualizing and exploring data indexed by the Data Search service.

### Using Kibana with FlowX Data Search

1. Connect Kibana to the same Elasticsearch instance
2. Create an index pattern matching your configured index name
3. Use the Discover tab to explore indexed data
4. Create visualizations and dashboards based on your data

<Info>
  Kibana is an open-source data visualization and exploration tool designed primarily for Elasticsearch. It serves as the visualization layer for the Elastic Stack, allowing users to interact with their data stored in Elasticsearch to perform various activities such as querying, analyzing, and visualizing data. For more information, visit the [Kibana official documentation](https://www.elastic.co/guide/en/kibana/current/index.html).
</Info>

***

## Best practices

1. **Security**:
   * Store sensitive credentials in Kubernetes Secrets
   * Use TLS for Elasticsearch and Kafka communication
   * Implement network policies to restrict access

2. **Performance**:
   * Scale the number of replicas based on query load
   * Adjust Kafka consumer threads based on message volume
   * Configure appropriate resource limits and requests

3. **Monitoring**:
   * Set up monitoring for Elasticsearch, Kafka, and Redis
   * Create alerts for service availability and performance
   * Monitor disk space for Elasticsearch data nodes

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Elasticsearch connection failures">
    **Symptoms:** Service fails to start or search requests return errors.

    **Solutions:**

    1. Verify Elasticsearch is running and accessible at the configured URL
    2. Check that credentials in `SPRING_ELASTICSEARCH_REST_USERNAME` and `SPRING_ELASTICSEARCH_REST_PASSWORD` are correct
    3. Ensure SSL settings match your environment — set `SPRING_ELASTICSEARCH_REST_DISABLESSL` to `true` if not using TLS
    4. Confirm the protocol in `SPRING_ELASTICSEARCH_REST_PROTOCOL` matches your Elasticsearch setup (`https` or `http`)
  </Accordion>

  <Accordion title="Database and Redis issues">
    **Symptoms:** Cache misses, stale search results, or Redis connection errors.

    **Solutions:**

    1. Verify Redis is running and accessible
    2. Check Redis authentication credentials
    3. Ensure network policies allow traffic between the Data Search pod and Redis
    4. Monitor Redis memory usage — eviction policies may cause cache misses under high load
  </Accordion>

  <Accordion title="Kafka sync failures">
    **Symptoms:** Search requests are not received or results are not delivered back to the engine.

    **Solutions:**

    1. Verify Kafka topics exist — check that `KAFKA_TOPIC_DATA_SEARCH_IN` and `KAFKA_TOPIC_DATA_SEARCH_OUT` topics are created
    2. Check Kafka permissions for the consumer group
    3. Ensure bootstrap servers in `KAFKA_BOOTSTRAP_SERVERS` are correctly specified
    4. If using OAuth, verify the token endpoint is accessible and credentials are valid
  </Accordion>

  <Accordion title="Indexing performance">
    **Symptoms:** Slow search responses, high latency, or timeouts.

    **Solutions:**

    1. Increase `KAFKA_CONSUMER_THREADS` to process more messages in parallel
    2. Verify the Elasticsearch cluster health — yellow or red status impacts performance
    3. Check index size and shard distribution in Elasticsearch
    4. Monitor Elasticsearch JVM heap usage and adjust resource limits if needed
    5. Review the `KAFKA_MESSAGE_MAX_BYTES` setting if large payloads are being processed
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Elasticsearch Indexing" icon="magnifying-glass" href="./flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing">
    Configure Elasticsearch indexing for process data
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Speech to Text setup
Source: https://docs.flowx.ai/5.9/setup-guides/speech-to-text-setup

Configure the Speech to Text service for audio transcription and text-to-speech capabilities.

The Speech to Text service is a Python-based microservice that provides audio transcription using OpenAI Whisper (local or API) and text-to-speech via the OpenAI TTS API. It supports both synchronous REST calls and asynchronous Kafka job processing for long-running audio files.

## Dependencies

The Speech to Text service connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — async job processing for transcription requests from Integration Designer, plus subscription to the AI Providers cache invalidation topic
* **S3-compatible storage** (MinIO or AWS S3) — audio file retrieval and result storage
* **organization-manager** — resolves OpenAI credentials and model assignments from the AUDIO capability configured in [AI Providers](/5.9/ai-platform/ai-providers)
* **OpenAI API key** (fallback) — used for local development, MCP usage, or when no tenant context is available on a request
* **ffmpeg** — required for audio decoding (included in Docker image)

<Info>
  The local Whisper transcription engine runs on-device and does not require any OpenAI credentials. Only cloud transcription (`/transcribe/openai`) and TTS (`/tts/openai`) need credentials, which are resolved from the organization's AUDIO capability when tenant headers are present on the request.
</Info>

***

## Capabilities

### What it can do

* **Local transcription**: On-device transcription using any Whisper model (`base`, `small`, `medium`, `large`, `turbo`) with automatic language detection
* **Cloud transcription**: OpenAI Whisper API with automatic chunking of long audio into 10-minute segments
* **Text-to-speech**: OpenAI TTS API with multiple models (`tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`) and voice options
* **Segment-level timing**: Returns word-level segments with start/end timestamps
* **Language detection**: Automatic source language detection with confidence probabilities
* **Long audio support**: Kafka-based async processing for files over 15 minutes

### Supported audio formats

| Format | Extensions     |
| ------ | -------------- |
| MP3    | `.mp3`         |
| WAV    | `.wav`         |
| FLAC   | `.flac`        |
| AAC    | `.aac`, `.m4a` |
| OGG    | `.ogg`         |

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/speech-to-text`).

| Endpoint                                   | Method | Purpose                                    |
| ------------------------------------------ | ------ | ------------------------------------------ |
| `/api/v1/speech-to-text/transcribe`        | POST   | Transcribe audio using local Whisper model |
| `/api/v1/speech-to-text/transcribe/openai` | POST   | Transcribe audio using OpenAI Whisper API  |
| `/api/v1/speech-to-text/tts/openai`        | POST   | Text-to-speech using OpenAI TTS API        |
| `/api/v1/speech-to-text/info/health`       | GET    | Health check                               |

***

## Configuration

### Server configuration

| Environment Variable | Description                                 | Default Value     |
| -------------------- | ------------------------------------------- | ----------------- |
| `URL_PREFIX`         | FastAPI root path for reverse proxy routing | `/speech-to-text` |
| `PORT`               | API port                                    | `8080`            |
| `GUNICORN_WORKERS`   | Number of Gunicorn worker processes         | `2`               |
| `GUNICORN_TIMEOUT`   | Worker timeout in seconds                   | `600`             |

<Tip>
  Increase `GUNICORN_TIMEOUT` for long audio files. The default `600` seconds works for most files; increase it further for very long recordings.
</Tip>

***

### Whisper model configuration

| Environment Variable   | Description                                                                                                                                                    | Default Value |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `WHISPER_MODEL`        | Local Whisper model name                                                                                                                                       | `turbo`       |
| `OPENAI_API_KEY`       | OpenAI API key — fallback for local dev, MCP, or requests without tenant context. In production, credentials resolve from the organization's AUDIO capability. | -             |
| `OPENAI_WHISPER_MODEL` | Fallback model for OpenAI cloud transcription when no tenant context is present or the resolver returns no model                                               | `whisper-1`   |

<Info>
  The primary source for OpenAI credentials and the transcription model is the **AUDIO capability** configured under **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**. The env vars above are used only when tenant context is missing or AUDIO is not configured for the organization. See [AI providers and model configuration](/5.9/ai-platform/ai-providers).
</Info>

Available local Whisper models:

| Model    | Size    | Speed   | Accuracy | Use case                                            |
| -------- | ------- | ------- | -------- | --------------------------------------------------- |
| `base`   | 74 MB   | Fastest | Low      | Quick prototyping, non-critical transcription       |
| `small`  | 244 MB  | Fast    | Medium   | General use with limited resources                  |
| `medium` | 769 MB  | Medium  | Good     | Balanced speed and accuracy                         |
| `large`  | 1.55 GB | Slow    | High     | High-accuracy requirements                          |
| `turbo`  | 809 MB  | Fast    | High     | Recommended default — best speed/accuracy trade-off |

<Warning>
  Larger Whisper models require significantly more memory. The `large` model needs at least 4 Gi RAM per worker. Plan memory limits accordingly and keep `GUNICORN_WORKERS` low when using larger models.
</Warning>

***

### Text-to-speech configuration

TTS is configured per-request via the API. Available options:

| Parameter | Options                                                                     | Default |
| --------- | --------------------------------------------------------------------------- | ------- |
| Model     | `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`                                      | `tts-1` |
| Voice     | `alloy`, `ash`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer` | `alloy` |

<Info>
  The `gpt-4o-mini-tts` model supports additional voices: `ballad`, `verse`, `marin`, `cedar`.
</Info>

***

### Tenant context

The Speech to Text service resolves OpenAI credentials per organization via the `llm-config` library. To route a request to the correct organization's AUDIO capability, the caller must propagate tenant context.

#### REST requests

Integration Designer and other upstream services must include these headers on every call to `/transcribe/openai` and `/tts/openai`:

| Header               | Purpose                                                     |
| -------------------- | ----------------------------------------------------------- |
| `Fx-Organization-Id` | Organization UUID — used to resolve the AUDIO capability    |
| `Fx-Workspace-Id`    | Workspace UUID — used when workspace-scoped overrides exist |

The `TenantContextMiddleware` reads these headers and sets the tenant context for the duration of the request. When neither header is present, the service falls back to the `OPENAI_API_KEY` env var.

#### Kafka jobs

Transcription requests published to `ai.flowx.ai-platform.speech-to-text.job.request.v1` must include `organizationId` and `workspaceId` fields in the payload. The job consumer reads these fields and sets the tenant context before invoking the transcription resolver.

<Info>
  Cache invalidation for AI provider configuration changes is delivered via Kafka. The service subscribes to `ai.flowx.llm.config.changed.v1` automatically on startup — no manual topic creation is required for invalidation, but the topic must exist in the cluster.
</Info>

***

### Kafka configuration (optional)

The Speech to Text service supports Kafka for async job processing of long-running audio files (15+ minutes) that would timeout via REST. The request, response, and DLQ topics are declared in the standard FlowX Kafka topics values (`kafka-topics.yaml.gotmpl`) and are provisioned automatically with the standard deployment.

<Info>
  If you run a non-standard Kafka setup that does not use the FlowX-managed topic provisioning, create the request and response topics manually before enabling the consumer.
</Info>

#### Core Kafka settings

| Environment Variable         | Description                                    | Default Value |
| ---------------------------- | ---------------------------------------------- | ------------- |
| `KAFKA_BOOTSTRAP_SERVERS`    | Kafka broker address                           | `kafka:9092`  |
| `KAFKA_CONSUMER_ENABLED`     | Enable Kafka consumer (`0` to turn off)        | `1`           |
| `KAFKA_CONSUMER_GROUPID`     | Consumer group ID                              | `ai-services` |
| `KAFKA_SECURITY_ENABLED`     | Enable SASL/OAUTHBEARER auth (`0` to turn off) | `0`           |
| `KAFKA_MAX_POLL_INTERVAL_MS` | Max poll interval (ms)                         | `600000`      |

<Tip>
  The default `KAFKA_MAX_POLL_INTERVAL_MS` is set to 10 minutes (600000 ms) to prevent consumer rebalancing during long transcriptions. Increase this value if you regularly process audio files longer than 10 minutes.
</Tip>

#### Topic configuration

| Environment Variable         | Description                                                                                                                                                                    | Default Value                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `KAFKA_JOB_REQUEST_TOPIC`    | Incoming transcription requests (from Integration Designer)                                                                                                                    | `ai.flowx.ai-platform.speech-to-text.job.request.v1`  |
| `KAFKA_JOB_RESPONSE_TOPIC`   | Outgoing transcription responses (to Integration Designer)                                                                                                                     | `ai.flowx.ai-platform.speech-to-text.job.response.v1` |
| *(subscribed automatically)* | AI Providers cache invalidation — consumed by the `llm-config` resolver to refresh cached AUDIO capability assignments when an organization admin updates Defaults & Fallbacks | `ai.flowx.llm.config.changed.v1`                      |

<Info>
  The Speech to Text service integrates with [flx-job-lib](https://github.com/flowx-ai/flowx-job-lib) for async job processing. On startup, the service verifies Kafka connectivity and starts a background consumer.
</Info>

***

### Storage configuration (MinIO / S3)

The Speech to Text service reads audio files from and writes results to S3-compatible storage.

| Environment Variable         | Description           | Default Value |
| ---------------------------- | --------------------- | ------------- |
| `MINIO_DOCUMENTS_URL`        | MinIO/S3 endpoint URL | -             |
| `MINIO_DOCUMENTS_ACCESS_KEY` | MinIO access key      | -             |
| `MINIO_DOCUMENTS_SECRET_KEY` | MinIO secret key      | -             |
| `MINIO_DOCUMENTS_BUCKET`     | MinIO bucket name     | -             |

***

### Observability (optional)

| Environment Variable | Description                                         | Default Value |
| -------------------- | --------------------------------------------------- | ------------- |
| `USE_OBSERVATORY`    | Enable FlowX Observatory middleware (`1` to enable) | `0`           |

***

### FLEURS evaluation (optional)

The service can optionally download Google FLEURS datasets at startup for language evaluation and benchmarking.

| Environment Variable | Description                           | Default Value             |
| -------------------- | ------------------------------------- | ------------------------- |
| `FLEURS_LANGS`       | Comma-separated FLEURS language codes | `en_us,hu_hu`             |
| `FLEURS_SPLIT`       | FLEURS dataset split                  | `test`                    |
| `FLEURS_CACHE_DIR`   | Dataset cache directory               | `/flowx/code/data/fleurs` |

<Info>
  FLEURS datasets are used for evaluating transcription accuracy across languages. This is not required for production use — skip this configuration unless you are benchmarking transcription quality.
</Info>

***

## Kafka job processing

The Speech to Text service processes transcription requests asynchronously via Kafka. Integration Designer sends requests to the job request topic, and the service writes results to S3 and responds through the job response topic.

### Request payload

| Field             | Type     | Default                            | Description                                                                                    |
| ----------------- | -------- | ---------------------------------- | ---------------------------------------------------------------------------------------------- |
| `fileStoragePath` | `string` | *(required)*                       | Path to audio file in MinIO/S3                                                                 |
| `provider`        | `string` | `local`                            | `local` for on-device Whisper, `openai` for OpenAI Whisper API                                 |
| `organizationId`  | `string` | *(required for `openai` provider)* | Organization UUID — sets tenant context so the resolver can fetch AUDIO capability credentials |
| `workspaceId`     | `string` | -                                  | Workspace UUID — used for workspace-scoped overrides                                           |

### Response flow

1. Integration Designer publishes a transcription request to `ai.flowx.ai-platform.speech-to-text.job.request.v1`
2. Speech to Text downloads the audio file from S3, transcribes it, and stores the result in S3
3. Speech to Text publishes a response with the result path to `ai.flowx.ai-platform.speech-to-text.job.response.v1`
4. Integration Designer retrieves the result (text, language, segments with timestamps) from S3

***

## Deployment and sizing

### Docker

* Base image: Python 3.13
* Port: `8080`
* Health check: `/speech-to-text/api/v1/speech-to-text/info/health`
* Requires ffmpeg (included in Docker image)

### Kubernetes configuration

<Tabs>
  <Tab title="Turbo model (recommended)">
    | Setting            | Value   |
    | ------------------ | ------- |
    | Replicas           | 2       |
    | CPU requests       | 2 cores |
    | CPU limits         | 4 cores |
    | RAM requests       | 2 Gi    |
    | RAM limits         | 4 Gi    |
    | `WHISPER_MODEL`    | `turbo` |
    | `GUNICORN_WORKERS` | `2`     |
  </Tab>

  <Tab title="Large model (high accuracy)">
    | Setting            | Value   |
    | ------------------ | ------- |
    | Replicas           | 2       |
    | CPU requests       | 4 cores |
    | CPU limits         | 8 cores |
    | RAM requests       | 4 Gi    |
    | RAM limits         | 8 Gi    |
    | `WHISPER_MODEL`    | `large` |
    | `GUNICORN_WORKERS` | `1`     |
  </Tab>
</Tabs>

<Warning>
  The Whisper model is loaded into memory at startup. Each Gunicorn worker loads its own copy of the model. With the `large` model (\~1.55 GB), keep `GUNICORN_WORKERS` at `1` to avoid OOM kills. Scale horizontally with more pods instead.
</Warning>

***

## Verify your setup

<Check>
  The Speech to Text pod is running: `kubectl get pods -l app=speech-to-text`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://speech-to-text:8000/api/v1/speech-to-text/info/health`
</Check>

<Check>
  Whisper model loaded successfully — check pod logs for model initialization messages at startup
</Check>

<Check>
  Kafka consumer is connected — check pod logs for `Kafka consumer started` message at startup
</Check>

<Check>
  Integration Designer can reach the service — verify `FLOWX_SPEECHTOTEXT_BASEURL` is set in [Integration Designer setup](/5.9/setup-guides/integration-designer-setup)
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pod fails to start or crashes">
    **Symptoms:** Pod stays in CrashLoopBackOff or never becomes ready.

    **Solutions:**

    * Check that memory limits are sufficient for the configured Whisper model
    * Verify ffmpeg is available (included in Docker image, may need manual install for local dev)
    * Review pod logs for model download or loading errors
    * Ensure the S3/MinIO endpoint is reachable if Kafka consumer is enabled
  </Accordion>

  <Accordion title="Transcription jobs not being processed">
    **Symptoms:** Integration Designer sends transcription requests but no results are returned.

    **Solutions:**

    * Verify `KAFKA_CONSUMER_ENABLED` is set to `1`
    * Check that `KAFKA_JOB_REQUEST_TOPIC` matches the topic Integration Designer publishes to
    * Ensure the Kafka consumer group (`KAFKA_CONSUMER_GROUPID`) has no conflicting consumers
    * Review pod logs for Kafka connection or authentication errors
  </Accordion>

  <Accordion title="Transcription quality is poor">
    **Symptoms:** Transcription text is inaccurate or contains many errors.

    **Solutions:**

    * Upgrade to a larger Whisper model (`turbo` or `large` instead of `base`)
    * Check audio quality — low bitrate or noisy recordings reduce accuracy
    * For non-English audio, use the `large` model which has better multilingual support
    * Try the OpenAI Whisper API (`provider: openai`) for comparison
  </Accordion>

  <Accordion title="Consumer rebalancing during long transcriptions">
    **Symptoms:** Kafka consumer drops out mid-transcription, causing job failures.

    **Solutions:**

    * Increase `KAFKA_MAX_POLL_INTERVAL_MS` beyond the expected transcription time
    * For very long audio files (30+ minutes), set to `1800000` (30 minutes)
    * Consider splitting long audio files before submitting
  </Accordion>

  <Accordion title="OOM kills with large Whisper models">
    **Symptoms:** Pods restart with OOMKilled status.

    **Solutions:**

    * Reduce `GUNICORN_WORKERS` to `1` — each worker loads its own model copy
    * Increase memory limits (4 Gi minimum for `turbo`, 8 Gi for `large`)
    * Use a smaller model (`small` or `base`) if accuracy requirements allow
    * Scale horizontally with more single-worker pods
  </Accordion>

  <Accordion title="OpenAI API errors">
    **Symptoms:** Cloud transcription or TTS requests fail with API errors.

    **Solutions:**

    * Confirm the request includes `Fx-Organization-Id` (REST) or `organizationId` (Kafka). Without tenant context, the service falls back to `OPENAI_API_KEY`, which may not be set in production deployments.
    * Verify the organization's AUDIO capability is configured under **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**. Pod logs show `no AUDIO capability configured for org, falling back to env` when missing.
    * If falling back to env, verify `OPENAI_API_KEY` is set and valid.
    * Check API rate limits on your OpenAI account.
    * For large files, the service automatically chunks audio into 10-minute segments — ensure network is stable.
    * Review pod logs for specific API error messages.
  </Accordion>

  <Accordion title="AI Providers cache not refreshing">
    **Symptoms:** Organization admin updates the AUDIO model in Defaults & Fallbacks, but the service continues to use the previous model.

    **Solutions:**

    * Verify the Kafka topic `ai.flowx.llm.config.changed.v1` exists in the cluster and the service has consumer permissions.
    * Check pod logs at startup for `LLM config resolver initialized`. If this line is missing or followed by `falling back to env vars`, the resolver did not start — the service is permanently in fallback mode and will not pick up AI Providers changes.
    * Restart the pods to force a cache refresh if the Kafka topic is unreachable.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Integration Designer setup" icon="pencil" href="./integration-designer-setup">
    Configure Integration Designer, which orchestrates Speech to Text jobs
  </Card>

  <Card title="Speech to Text node" icon="microphone" href="../ai-platform/agent-builder/speech-to-text">
    Configure the Speech to Text workflow node in Integration Designer
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="Web Crawler setup" icon="spider-web" href="./web-crawler-setup">
    Configure the Web Crawler service for web page extraction
  </Card>
</CardGroup>


# SpiceDB setup
Source: https://docs.flowx.ai/5.9/setup-guides/spicedb

This guide covers the step-by-step installation and configuration of SpiceDB for FlowX deployments, including operator installation, database setup, and service integration.

## Overview

SpiceDB is a database for managing authorization policies. It is used to store and manage the authorization policies for the Authorization Service in FlowX's multi-tenant architecture.

<Info>
  **Scope: design-time permissions only.** SpiceDB backs build-time access checks in the FlowX Designer (who can edit which workspace, project, or resource). Runtime permissions — which end users can interact with which solution at execution time — use a separate, custom implementation that does not call SpiceDB. The two systems coexist and don't interact at runtime. See [Runtime authorization](./access-management/runtime-authorization) for the runtime model.
</Info>

<Info>
  For more information about SpiceDB, see the [SpiceDB documentation](https://authzed.com/docs/spicedb/getting-started/discovering-spicedb).
</Info>

## Prerequisites

<CardGroup>
  <Card title="Infrastructure" icon="server">
    * Kubernetes cluster with admin access
    * PostgreSQL database server
    * Network connectivity between SpiceDB and FlowX services
  </Card>

  <Card title="FlowX Integration" icon="puzzle-piece">
    * FlowX platform components that integrate with SpiceDB
    * CAS client library configuration in all FlowX services
    * Proper secret management for authentication
  </Card>
</CardGroup>

## FlowX customizations

The FlowX platform includes several customizations to the standard SpiceDB deployment:

* **Namespace-restricted operator**: Uses Role and RoleBinding instead of ClusterRole and ClusterRoleBinding for enhanced security
* **Platform Health Monitoring**: Automatic health check configuration for FlowX platform monitoring (`/healthz` endpoint on port 8443)
* **Migration Job Optimization**: Configured retry limits (3 attempts) and timeouts (30 minutes) for schema migrations
* **Resource Optimization**: Production-ready resource requests and limits based on real-world usage
* **Service Annotations**: FlowX-specific service annotations for platform integration

<Warning>
  These customizations ensure SpiceDB operates securely within the FlowX platform architecture and integrates properly with platform monitoring and status systems.
</Warning>

## Installation steps

### Step 1: Install SpiceDB operator

<Info>
  The FlowX platform uses a customized SpiceDB operator that operates within a specific namespace, using Role and RoleBinding instead of ClusterRole and ClusterRoleBinding for enhanced security and isolation.
</Info>

Install the namespace-restricted SpiceDB operator using Helm:

```bash theme={"system"}
# Install the operator in the same namespace as FlowX
helm install spicedb-operator your-org/spicedb-operator \
  --namespace your-flowx-namespace \
  --create-namespace \
  --version <OPERATOR_VERSION>
```

<Info>
  The operator must be installed in the same namespace as FlowX because it operates with namespace-scoped permissions and cannot access other namespaces.
</Info>

**Example values.yaml for the operator:**

```yaml theme={"system"}
# SpiceDB Operator Configuration
replicaCount: 1

serviceAccount:
  create: true
  name: "spicedb-operator"

# Resource limits
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi
```

<Warning>
  This operator is restricted to operate within a single namespace (the namespace where it is installed) and does not require cluster-wide permissions. The operator automatically watches the namespace where it is deployed.
</Warning>

Verify the operator is running:

```bash theme={"system"}
kubectl get pods -l app.kubernetes.io/name=spicedb-operator -n your-flowx-namespace
```

<Info>
  The operator pod will have a name in the format: `spicedb-operator-<hash>-<hash>` (e.g., `spicedb-operator-dd8f97d95-s78fc`)
</Info>

### Step 2: Create SpiceDB database

Create a dedicated PostgreSQL database and user for SpiceDB:

```sql theme={"system"}
-- Connect to PostgreSQL as admin user
CREATE DATABASE spicedb;
CREATE USER spicedb_user WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE spicedb TO spicedb_user;
```

<Warning>
  SpiceDB requires a dedicated PostgreSQL database. Do not share with other FlowX services.
</Warning>

### Step 3: Create Kubernetes Secret

Create the `spicedb` secret with the required credentials:

```yaml theme={"system"}
apiVersion: v1
kind: Secret
metadata:
  name: spicedb
type: Opaque
data:
  datastore_uri: <base64-encoded-postgres-connection-string>
  preshared_key: <base64-encoded-secure-token>
```

The secret should contain:

```bash theme={"system"}
# Raw values (encode these in base64 for the secret)
datastore_uri='postgres://USERNAME:PASSWORD@postgresql:5432/spicedb?sslmode=disable'
preshared_key='REPLACEME'
```

<Tip>
  Generate a secure preshared key using: `openssl rand -base64 32`
</Tip>

### Step 4: Deploy SpiceDB cluster

<Info>
  The FlowX platform uses a customized SpiceDB cluster chart that includes additional patches for platform status monitoring, health checks, and optimized resource configurations. The deployment uses a dedicated `spicedb` service account for proper RBAC permissions.
</Info>

Install the SpiceDB cluster using Helm (includes platform-status patches):

```bash theme={"system"}
# Install the cluster (using your organization's Helm repository)
helm install spicedb your-org/spicedb-cluster \
  --namespace your-namespace \
  --version <CHART_VERSION> \
  --set version=<SPICEDB_VERSION> \
  --set secretName=spicedb
```

**Custom values.yaml (optional):**

```yaml theme={"system"}
# FlowX SpiceDB Cluster Configuration
version: <SPICEDB_VERSION>
logLevel: debug
datastoreEngine: postgres
httpEnabled: true
secretName: spicedb
replicas: 2

# Optimized resource requests (matches production)
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "1"
    memory: 1Gi
```

<Info>
  **FlowX Platform Integration**: The FlowX SpiceDB chart automatically configures health monitoring annotations on the Service resource. These annotations are hardcoded in the chart and include:

  * `flowx.ai/health: "true"`
  * `flowx.ai/health-path: "/healthz"`
  * `flowx.ai/health-port: "8443"`

  No additional configuration is needed for platform health monitoring.
</Info>

<Warning>
  For production deployments, ensure `replicas: 2` or higher for high availability. The FlowX chart includes automatic health monitoring and migration job configurations.
</Warning>

### Step 5: Update FlowX services

<Info>
  The following services need a cas-lib configuration:

  * authorization-service
  * application-manager
  * authorization-system
  * cms-core
  * data-sync
  * document-plugin
  * integration-designer
  * notification-plugin
  * process-engine
  * runtime-manager
  * task-management-plugin
</Info>

Configure FlowX services to connect to SpiceDB. The following configuration values are already set by default in FlowX:

```bash theme={"system"}
FLOWX_SPICEDB_HOST: spicedb #default value
FLOWX_SPICEDB_PORT: 50051 #default value
```

**required configuration**: Add the SpiceDB token to your FlowX services:

```bash theme={"system"}
FLOWX_SPICEDB_TOKEN: REPLACEME
```

#### Helm values configuration

Add the token reference to your Helm values using `extraEnvVarsMultipleSecretsCustomKeys`:

```yaml theme={"system"}
extraEnvVarsMultipleSecretsCustomKeys:
  - name: spicedb
    secrets:
      FLOWX_SPICEDB_TOKEN: preshared_key
```

<Info>
  This configuration tells Helm to:

  1. Look for the existing Kubernetes Secret named `spicedb` (created in Step 3)
  2. Take the value from the `preshared_key` key in that secret
  3. Mount it as environment variable `FLOWX_SPICEDB_TOKEN` in FlowX service pods
</Info>

<Warning>
  **Token Synchronization**: The `preshared_key` value in the SpiceDB secret must match the `FLOWX_SPICEDB_TOKEN` in all FlowX microservices.
</Warning>

## Verification

Verify your SpiceDB deployment:

<Steps>
  <Step title="Check SpiceDB Pods">
    Ensure SpiceDB pods are running:

    ```bash theme={"system"}
    kubectl get pods -l app.kubernetes.io/name=spicedb
    ```
  </Step>

  <Step title="Test Connectivity">
    Verify SpiceDB is accessible on port 50051:

    ```bash theme={"system"}
    kubectl port-forward svc/spicedb 50051:50051
    # Test connection from another terminal
    grpcurl -plaintext localhost:50051 list
    ```
  </Step>

  <Step title="Check FlowX Integration">
    Review FlowX service logs for successful SpiceDB connection:

    ```bash theme={"system"}
    kubectl logs -l app=authorization-system | grep -i spicedb
    ```
  </Step>
</Steps>

## Configuration reference

### Required environment variables

| Variable                     | Required | Description                            | Default Value                                                          | Notes                                                                                |
| ---------------------------- | -------- | -------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `SPICEDB_DATASTORE_ENGINE`   | ✅        | Database engine type                   | `postgres`                                                             | Only PostgreSQL is supported in FlowX                                                |
| `SPICEDB_DATASTORE_CONN_URI` | ✅        | PostgreSQL connection string           | `postgres://postgres:password@postgresql:5432/spicedb?sslmode=disable` | Use Kubernetes Secret - include `sslmode=disable` for internal cluster communication |
| `SPICEDB_GRPC_PRESHARED_KEY` | ✅        | Pre-shared key for gRPC authentication | `your-secure-key-here`                                                 | **This becomes `FLOWX_SPICEDB_TOKEN` in FlowX services**                             |

### Optional configuration

| Variable                           | Required | Description                               | Default Value | Notes                                                      |
| ---------------------------------- | -------- | ----------------------------------------- | ------------- | ---------------------------------------------------------- |
| `SPICEDB_DISPATCH_CLUSTER_ENABLED` | ⚠️       | Enable cluster mode for multiple replicas | `true`        | Required for production deployments with multiple replicas |
| `SPICEDB_LOG_LEVEL`                | ⚠️       | Logging verbosity level                   | `debug`       | Use `debug` for troubleshooting, `info` for production     |

## Customer-specific configuration

<Warning>
  **Required Customization**: These values must be updated for each deployment environment.
</Warning>

* **Database Connection**: Update `datastore_uri` with your PostgreSQL credentials and hostname
* **Security Token**: Generate a unique `preshared_key` for your deployment


# Task management setup
Source: https://docs.flowx.ai/5.9/setup-guides/task-management-plugin-setup

Configure and deploy the Task Management plugin as a Docker microservice within the FlowX platform.

The Task Management plugin is available as a Docker image and serves as a dedicated microservice within the FlowX platform ecosystem.

## Dependencies

Before setting up the plugin, ensure you have the following dependencies:

* A [MongoDB](https://www.mongodb.com/) database for task storage
* A connection to the RuntimeDB for operational data
* Access to the database used by the FlowX Engine
* Connection to the Kafka instance used by the FlowX Engine
* A [Redis](https://redis.io/) instance for caching and performance optimization

While many configuration properties come pre-configured, several environment variables must be explicitly set for proper functionality.

## Authorization configuration & access roles

The Task Management plugin validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-task-management-plugin-sa`                                                                  |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Info>
  **Starting with 5.9.0, the Task Management plugin no longer connects to the identity provider for user lookup.** Task operations resolve users through FlowX runtime authorization instead. The previously required `view-users`, `query-users`, and `query-groups` realm-management roles on the service account, the `OPENID_PROVIDER` / `OPENID_ENTRA_*` settings, and the `openid:` Helm values block are obsolete and can be removed from your deployment.
</Info>

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

For more detailed information about configuring the service account:

<Card title="Task Management Service Account" href="../setup-guides/access-management/configuring-an-iam-solution#task-management-service-account" icon="file" />

### FlowX Engine datasource configuration

The service needs access to process instance data from the engine database. Configure these connection parameters:

| Environment Variable         | Description                      | Default Value                                    |
| ---------------------------- | -------------------------------- | ------------------------------------------------ |
| `SPRING_DATASOURCE_URL`      | JDBC URL for the engine database | `jdbc:postgresql://onboardingdb:5432/onboarding` |
| `SPRING_DATASOURCE_USERNAME` | Database username                | `postgres`                                       |
| `SPRING_DATASOURCE_PASSWORD` | Database password                | `password`                                       |

### MongoDB configuration

Configure access to the primary MongoDB instance:

| Environment Variable      | Description            | Default Value                                                                                                                                                           |
| ------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/task-management-plugin` |
| `DB_USERNAME`             | MongoDB username       | `task-management-plugin`                                                                                                                                                |
| `DB_PASSWORD`             | MongoDB password       | `password`                                                                                                                                                              |

<Info>
  Task Manager requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.
</Info>

### Runtime MongoDB configuration

<Info>
  Task Manager requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.
</Info>

Enable the Runtime MongoDB connection:

| Environment Variable                  | Description                                                                                                                              | Default Value                                                                                                                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection                                                                                                        | `true`                                                                                                                                                                         |
| `SPRING_DATA_MONGODB_RUNTIME_URI`     | URI for connecting to MongoDB Runtime. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |

### Redis configuration

Task Management Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable         | Description                   | Example Value | Status          |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST`     | Redis server hostname         | `localhost`   | **Recommended** |
| `SPRING_DATA_REDIS_PORT`     | Redis server port             | `6379`        | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | -             | **Recommended** |
| `REDIS_TTL`                  | Cache TTL in milliseconds     | `5000000`     | Optional        |

<Info>
  Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
</Info>

<Info>
  For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
</Info>

## Kafka configuration

Configure the Kafka integration using these environment variables:

### Core Kafka settings

| Environment Variable                 | Description                                             | Default Value                     |
| ------------------------------------ | ------------------------------------------------------- | --------------------------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`      | Address of the Kafka server(s)                          | `localhost:9092`                  |
| `SPRING_KAFKA_SECURITY_PROTOCOL`     | Security protocol for Kafka connections                 | `PLAINTEXT`                       |
| `SPRING_KAFKA_CONSUMER_GROUPID`      | Consumer group identifier                               | `task-management-plugin-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES`            | Maximum message size (bytes)                            | `52428800` (50 MB)                |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`   | Retry interval after authorization exceptions (seconds) | `10`                              |
| `KAFKA_CONSUMER_THREADS`             | Number of consumer threads                              | `3`                               |
| `KAFKA_CONSUMER_EXCLUDEUSERSTHREADS` | Number of threads for processing user exclusion events  | `3`                               |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |

### Kafka topics

#### Process management topics

| Environment Variable                     | Description                                        | Default Value                              |
| ---------------------------------------- | -------------------------------------------------- | ------------------------------------------ |
| `KAFKA_TOPIC_PROCESS_START_OUT`          | Topic for running hooks                            | `ai.flowx.core.trigger.start.process.v1`   |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_OUT`     | Topic for task operations (assign, unassign, etc.) | `ai.flowx.core.trigger.operation.v1`       |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_BULKOUT` | Topic for bulk operations on tasks                 | `ai.flowx.core.trigger.operations.bulk.v1` |

#### Scheduling topics

| Environment Variable                    | Description                                      | Default Value                               |
| --------------------------------------- | ------------------------------------------------ | ------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_IN`       | Topic for receiving scheduler messages for hooks | `ai.flowx.plugin.tasks.trigger.run.hook.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET`  | Topic for setting schedules                      | `ai.flowx.core.trigger.set.schedule.v1`     |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP` | Topic for stopping schedules                     | `ai.flowx.core.trigger.stop.schedule.v1`    |

#### User management topics

| Environment Variable                   | Description                     | Default Value                                    |
| -------------------------------------- | ------------------------------- | ------------------------------------------------ |
| `KAFKA_TOPIC_EXCLUDEUSERS_SCHEDULE_IN` | Topic for user exclusion events | `ai.flowx.plugin.tasks.trigger.exclude.users.v1` |

#### Task operations topics

| Environment Variable  | Description                               | Default Value                                |
| --------------------- | ----------------------------------------- | -------------------------------------------- |
| `KAFKA_TOPIC_TASK_IN` | Topic for incoming task creation messages | `ai.flowx.plugin.tasks.trigger.save.task.v1` |

#### Events and integration topics

| Environment Variable                    | Description                             | Default Value                                                    |
| --------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Topic for Events Gateway messages       | `ai.flowx.eventsgateway.receive.taskmanager.commands.message.v1` |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH`   | Topic for resource usage refresh events | `ai.flowx.application-version.resources-usages.refresh.v1`       |

<Info>
  The Engine listens for messages on topics with specific naming patterns. Ensure you use the correct outgoing topic names when configuring the Task Management plugin to maintain proper communication with the engine.
</Info>

## CAS lib configuration

| Environment Variable  | Description                  | Default Value   |
| --------------------- | ---------------------------- | --------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`       |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`         |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

## Logging configuration

Control logging verbosity with these environment variables:

| Environment Variable         | Description                        | Default Value |
| ---------------------------- | ---------------------------------- | ------------- |
| `LOGGING_LEVEL_ROOT`         | Root Spring Boot microservice logs | -             |
| `LOGGING_LEVEL_APP`          | Application-level logs             | `DEBUG`       |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver logs                | `INFO`        |
| `LOGGING_LEVEL_REDIS`        | Redis/Lettuce client log level     | `OFF`         |

## Ingress and CORS

The Task Management plugin is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/task`       | `/`              |
| public     | `/task`       | `/`              |

Paths are set through `services.task-management-plugin.ingress.admin.path` / `services.task-management-plugin.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                    | Default Value |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Task Management. | `-`           |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

## Filtering feature

| Environment Variable                  | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| `FLOWX_ALLOW_USERNAME_SEARCH_PARTIAL` | Enables filtering possible assignees by partial names |

## Scheduled jobs

Configure scheduled maintenance jobs:

| Environment Variable                          | Description                            | Default Value                    |
| --------------------------------------------- | -------------------------------------- | -------------------------------- |
| `SCHEDULER_USERSCACHESCLEANUP_CRONEXPRESSION` | Cron expression for user cache cleanup | `0 0 0 * *?` (daily at midnight) |

### Resource usage monitoring

The plugin includes a resource usage monitoring feature that can be configured:

| Environment Variable                                                       | Description                                            | Default Value                         |
| -------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------- |
| `FLOWX_LIB_RESOURCESUSAGES_ENABLED`                                        | Enable resource usage tracking                         | `true`                                |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED`                        | Enable refresh listener                                | `true`                                |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT`          | Number of threads for resource collection              | `5`                                   |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE`         | Maximum batch size for collection                      | `1000`                                |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGES_REFRESH` | Consumer group for resource usage refresh events       | `taskMgmtResourcesUsagesRefreshGroup` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGES_REFRESH` | Number of threads for processing resource usage events | `3`                                   |

### Database migration

The Task Management plugin uses Mongock for MongoDB migrations:

| Environment Variable            | Description                              | Default Value                             |
| ------------------------------- | ---------------------------------------- | ----------------------------------------- |
| `MONGOCK_CHANGELOGSSCANPACKAGE` | Package to scan for database change logs | `ai.flowx.task.management.config.mongock` |


# Web Crawler setup
Source: https://docs.flowx.ai/5.9/setup-guides/web-crawler-setup

Configure the Web Crawler service for web page crawling, content extraction, and AI-driven browser automation.

The Web Crawler is a Python-based microservice that crawls web pages using Playwright and extracts content as Markdown. It also provides AI-driven browser automation for multi-step web interactions.

## Dependencies

The Web Crawler connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — async job processing for crawl requests from Integration Designer
* [**Identity provider**](/5.9/setup-guides/access-management/configuring-an-iam-solution) (Keycloak or Azure AD) — authentication and Kafka OAuth
* [**CMS Core**](/5.9/setup-guides/cms-setup) — content management integration
* [**Document Plugin**](/5.9/setup-guides/documents-plugin-setup) — file upload for downloaded documents
* **S3-compatible storage** (MinIO or AWS S3) — storing crawl results and offloaded Kafka payloads
* **AI provider** (OpenAI, Anthropic, Ollama, Azure OpenAI, or GCP) — required only for browser automation features

***

## Capabilities

### What it can do

* **Single-page crawling**: Extract content from individual web pages as Markdown
* **Deep crawling**: Breadth-first crawling with configurable depth, concurrency, and rate limiting
* **PDF processing**: Dedicated scraping strategy for linked PDF documents
* **File downloads**: Automatic detection and upload of downloadable files (.docx, .xlsx, .pdf) to the Document Plugin
* **AI browser automation**: Multi-step browser interactions using Claude or GPT-4o via the browser-use library
* **Session management**: Persistent browser sessions for multi-step automation workflows
* **Per-level URL caps**: Configurable maximum pages per depth level during deep crawls
* **Multiple URL filters**: Configure up to 20 URL filter patterns per crawler from the **URL Filters** modal on the Web Crawler node to restrict deep crawls to matching URLs

### What it cannot do

* Cannot crawl pages that require JavaScript-based authentication (unless using browser automation)
* Cannot process audio or video content
* Cannot bypass CAPTCHAs or bot protection without proxy configuration

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/web-crawler`).

| Endpoint                                    | Method | Purpose                                 |
| ------------------------------------------- | ------ | --------------------------------------- |
| `/api/v1/web-crawler/parse`                 | POST   | Crawl URLs and extract Markdown content |
| `/api/v1/web-crawler/interact`              | POST   | Start AI browser automation session     |
| `/api/v1/web-crawler/interact/{session_id}` | POST   | Continue automation in existing session |
| `/api/v1/web-crawler/interact/{session_id}` | DELETE | Close browser session                   |
| `/api/v1/web-crawler/info/health`           | GET    | Health check                            |

***

## Configuration

### Server configuration

| Environment Variable | Description                                  | Default Value  |
| -------------------- | -------------------------------------------- | -------------- |
| `URL_PREFIX`         | FastAPI root path for reverse proxy routing  | `/web-crawler` |
| `VERSION`            | Service version identifier                   | `DEV`          |
| `VERBOSE`            | Enable verbose/debug logging (`1` to enable) | `0`            |
| `GUNICORN_WORKERS`   | Number of Gunicorn worker processes          | `1`            |
| `GUNICORN_TIMEOUT`   | Worker timeout in seconds                    | `600`          |

<Tip>
  Set `GUNICORN_TIMEOUT` to at least `600` (10 minutes). Deep crawls with multiple pages can take significant time depending on target site responsiveness and configured depth.
</Tip>

***

### Authentication configuration

#### Keycloak / OAuth2

| Environment Variable              | Description                           | Default Value                        |
| --------------------------------- | ------------------------------------- | ------------------------------------ |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | Keycloak server URL                   | *(required)*                         |
| `SECURITY_OAUTH2_REALM`           | Default Keycloak realm                | `flowx`                              |
| `SECURITY_OAUTH2_CLIENT_ID`       | Platform auth client ID               | `flowx-platform-authenticate`        |
| `SECURITY_OAUTH2_CLIENT_SECRET`   | Platform auth client secret           | `flowx-platform-authenticate-secret` |
| `SECURITY_PROVIDER`               | Auth provider (`KEYCLOAK` or `AZURE`) | `KEYCLOAK`                           |

#### Service account

The Web Crawler uses a service account for platform API calls (CMS, Document Plugin).

| Environment Variable          | Description                    | Default Value             |
| ----------------------------- | ------------------------------ | ------------------------- |
| `SERVICE_OAUTH_CLIENT_ID`     | Service account client ID      | `flowx-scheduler-core-sa` |
| `SERVICE_OAUTH_CLIENT_SECRET` | Service account client secret  | -                         |
| `SERVICE_OAUTH_CLIENT_REALM`  | Service account Keycloak realm | -                         |

***

### Kafka configuration

The Web Crawler uses Kafka for async job processing. Integration Designer sends crawl requests, and the Web Crawler returns results through Kafka topics.

#### Core Kafka settings

| Environment Variable      | Description                             | Default Value |
| ------------------------- | --------------------------------------- | ------------- |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker address                    | `kafka:9092`  |
| `KAFKA_CONSUMER_ENABLED`  | Enable Kafka consumer (`0` to turn off) | `1`           |
| `KAFKA_PRODUCER_ENABLED`  | Enable Kafka producer (`0` to turn off) | `1`           |
| `KAFKA_CONSUMER_GROUPID`  | Consumer group ID                       | `ai-services` |

#### Consumer tuning

| Environment Variable          | Description             | Default Value |
| ----------------------------- | ----------------------- | ------------- |
| `KAFKA_MAX_POLL_INTERVAL_MS`  | Max poll interval (ms)  | `300000`      |
| `KAFKA_SESSION_TIMEOUT_MS`    | Session timeout (ms)    | `300000`      |
| `KAFKA_HEARTBEAT_INTERVAL_MS` | Heartbeat interval (ms) | `10000`       |

<Tip>
  Increase `KAFKA_MAX_POLL_INTERVAL_MS` if deep crawls regularly exceed 5 minutes. The consumer will be removed from the group if processing takes longer than this interval.
</Tip>

#### OAuth authentication

When using `KAFKA_SECURITY_ENABLED=1`, the Web Crawler authenticates to Kafka using SASL/OAUTHBEARER via Keycloak.

| Environment Variable             | Description                                    | Default Value                                                                        |
| -------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------ |
| `KAFKA_SECURITY_ENABLED`         | Enable SASL/OAUTHBEARER auth (`0` to turn off) | `1`                                                                                  |
| `KAFKA_OAUTH_CLIENT_ID`          | Service account for Kafka SASL                 | `flowx-service-client`                                                               |
| `KAFKA_OAUTH_CLIENT_SECRET`      | Service account secret                         | -                                                                                    |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | Keycloak token endpoint for Kafka OAuth        | `{SECURITY_OAUTH2_BASE_SERVER_URL}/realms/kafka-authz/protocol/openid-connect/token` |

#### Topic configuration

| Environment Variable       | Description                                             | Default Value                       |
| -------------------------- | ------------------------------------------------------- | ----------------------------------- |
| `KAFKA_JOB_REQUEST_TOPIC`  | Incoming crawl job requests (from Integration Designer) | `ai.flowx.web-crawler.job.request`  |
| `KAFKA_JOB_RESPONSE_TOPIC` | Outgoing crawl job responses (to Integration Designer)  | `ai.flowx.web-crawler.job.response` |

<Info>
  The Web Crawler integrates with [flx-job-lib](https://github.com/flowx-ai/flowx-job-lib) for async job processing. On startup, the service verifies Kafka connectivity and starts a background consumer.
</Info>

#### Kafka payload offloading

When crawl results exceed the size limit, payloads are offloaded to S3-compatible storage.

| Environment Variable        | Description                                      | Default Value     |
| --------------------------- | ------------------------------------------------ | ----------------- |
| `KAFKA_OFFLOAD_BACKEND`     | Storage backend (`minio` or `azure`)             | `minio`           |
| `KAFKA_OFFLOAD_SIZE_LIMIT`  | Payload size threshold (bytes) before offloading | `512000`          |
| `KAFKA_OFFLOAD_ROOT_FOLDER` | Root folder for offloaded payloads               | `payload-offload` |

***

### Storage configuration

The Web Crawler stores crawl results in S3-compatible storage. Configure one of the following storage backends.

<Tabs>
  <Tab title="MinIO / S3">
    | Environment Variable         | Description                         | Default Value |
    | ---------------------------- | ----------------------------------- | ------------- |
    | `MINIO_DOCUMENTS_URL`        | MinIO/S3 endpoint URL               | -             |
    | `MINIO_DOCUMENTS_ACCESS_KEY` | MinIO access key                    | -             |
    | `MINIO_DOCUMENTS_SECRET_KEY` | MinIO secret key                    | -             |
    | `MINIO_DOCUMENTS_BUCKET`     | MinIO bucket name                   | -             |
    | `MINIO_DOCUMENTS_SECURE`     | Use HTTPS for MinIO (`1` to enable) | `0`           |
  </Tab>

  <Tab title="AWS S3">
    | Environment Variable                              | Description         | Default Value |
    | ------------------------------------------------- | ------------------- | ------------- |
    | `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`  | AWS S3 access key   | -             |
    | `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`  | AWS S3 secret key   | -             |
    | `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`  | AWS S3 endpoint URL | -             |
    | `APPLICATION_FILE_STORAGE_S3_PRIVATE_REGION`      | AWS S3 region       | -             |
    | `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME` | AWS S3 bucket name  | -             |
  </Tab>

  <Tab title="Azure Blob Storage">
    | Environment Variable              | Description                          | Default Value |
    | --------------------------------- | ------------------------------------ | ------------- |
    | `AZURE_STORAGE_CONNECTION_STRING` | Azure blob storage connection string | -             |
    | `AZURE_STORAGE_CONTAINER`         | Azure blob container name            | -             |
  </Tab>
</Tabs>

***

### Platform service URLs

| Environment Variable     | Description                              | Default Value                   |
| ------------------------ | ---------------------------------------- | ------------------------------- |
| `CMS_API_URL`            | CMS Core service URL                     | `http://cms-core:80`            |
| `DOCUMENT_PLUGIN_URL`    | Document Plugin URL (for file uploads)   | `http://document-plugin:80`     |
| `APP_MANAGER_API_URL`    | App Manager service URL                  | `http://application-manager:80` |
| `CMS_STATIC_ASSETS_PATH` | Static assets CDN path for CMS downloads | -                               |

***

### AI model configuration

Required only for the browser automation feature (`/interact` endpoints). The Web Crawler uses LLM models to drive browser interactions.

| Model type | Variable               | Purpose                            | Default  |
| ---------- | ---------------------- | ---------------------------------- | -------- |
| Chat       | `MODEL_TYPE`           | Primary LLM for browser automation | `OPENAI` |
| Vision     | `VISION_MODEL_TYPE`    | Visual page understanding          | `OPENAI` |
| Embedding  | `EMBEDDING_MODEL_TYPE` | Text embeddings                    | `OPENAI` |

| Environment Variable       | Description                            | Default Value |
| -------------------------- | -------------------------------------- | ------------- |
| `FALLBACK_MODEL_TYPE`      | Fallback LLM provider if primary fails | -             |
| `STRUCTURED_OUTPUT_METHOD` | Structured output method for LLM       | `json_schema` |

<Info>
  All model types support the same providers: `OPENAI`, `AZURE`, `OLLAMA`, `ANTHROPIC`, `GCP`, `CUSTOM_OPENAI`.
</Info>

#### Provider-specific variables

<Tabs>
  <Tab title="OpenAI">
    | Environment Variable          | Description          | Default Value            |
    | ----------------------------- | -------------------- | ------------------------ |
    | `OPENAI_API_KEY`              | OpenAI API key       | -                        |
    | `OPENAI_MODEL_NAME`           | Chat model name      | `gpt-4o-2024-08-06`      |
    | `OPENAI_VISION_MODEL_NAME`    | Vision model name    | `gpt-4o-2024-08-06`      |
    | `OPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |
    | `OPENAI_CHUNK_SIZE`           | Embedding chunk size | `1000`                   |
  </Tab>

  <Tab title="Anthropic">
    | Environment Variable          | Description       | Default Value |
    | ----------------------------- | ----------------- | ------------- |
    | `ANTHROPIC_API_KEY`           | Anthropic API key | -             |
    | `ANTHROPIC_MODEL_NAME`        | Chat model name   | -             |
    | `ANTHROPIC_VISION_MODEL_NAME` | Vision model name | -             |
  </Tab>

  <Tab title="Ollama">
    | Environment Variable          | Description          | Default Value     |
    | ----------------------------- | -------------------- | ----------------- |
    | `OLLAMA_BASE_URL`             | Ollama server URL    | -                 |
    | `OLLAMA_MODEL_NAME`           | Chat model name      | `llama3.2:latest` |
    | `OLLAMA_VISION_MODEL_NAME`    | Vision model name    | `llava:7b-v1.6`   |
    | `OLLAMA_EMBEDDING_MODEL_NAME` | Embedding model name | `all-minilm:33m`  |
  </Tab>

  <Tab title="Other providers">
    **Azure OpenAI:**

    | Environment Variable     | Description     | Default Value       |
    | ------------------------ | --------------- | ------------------- |
    | `AZUREOPENAI_MODEL_NAME` | Chat model name | `gpt-4o-2024-08-06` |

    **Google Cloud / Vertex AI:**

    | Environment Variable | Description             | Default Value    |
    | -------------------- | ----------------------- | ---------------- |
    | `GCP_PROJECT_ID`     | Google Cloud project ID | -                |
    | `GCP_LOCATION`       | Google Cloud region     | -                |
    | `GCP_MODEL_NAME`     | Chat model name         | `gemini-1.5-pro` |

    **Custom OpenAI-compatible:**

    | Environment Variable          | Description             | Default Value            |
    | ----------------------------- | ----------------------- | ------------------------ |
    | `CUSTOM_OPENAI_BASE_URL`      | API base URL            | `https://api.openai.com` |
    | `CUSTOM_OPENAI_CLIENT_ID`     | Client ID               | -                        |
    | `CUSTOM_OPENAI_SECRET_KEY`    | Secret key              | -                        |
    | `CUSTOM_OPENAI_CHAT_URL`      | Chat endpoint path      | `/chat/completions`      |
    | `CUSTOM_OPENAI_EMBEDDING_URL` | Embedding endpoint path | `/embeddings`            |
  </Tab>
</Tabs>

***

### PostgreSQL configuration

The Web Crawler uses PostgreSQL for embedding storage, memory, and chat history.

<Tabs>
  <Tab title="Embedding database">
    | Environment Variable          | Description   | Default Value        |
    | ----------------------------- | ------------- | -------------------- |
    | `POSTGRES_EMBEDDING_URI`      | Host and port | `postgresql-ai:5432` |
    | `POSTGRES_EMBEDDING_USERNAME` | Username      | `dip`                |
    | `POSTGRES_EMBEDDING_PASSWORD` | Password      | -                    |
    | `POSTGRES_EMBEDDING_DATABASE` | Database name | `dip`                |
  </Tab>

  <Tab title="Memory store">
    | Environment Variable       | Description   | Default Value        |
    | -------------------------- | ------------- | -------------------- |
    | `POSTGRES_MEMORY_URI`      | Host and port | `postgresql-ai:5432` |
    | `POSTGRES_MEMORY_USERNAME` | Username      | `memory`             |
    | `POSTGRES_MEMORY_PASSWORD` | Password      | -                    |
    | `PG_MEMORY_DB`             | Database name | `memory`             |
  </Tab>

  <Tab title="Chat history">
    | Environment Variable        | Description   | Default Value        |
    | --------------------------- | ------------- | -------------------- |
    | `POSTGRES_HISTORY_URI`      | Host and port | `postgresql-ai:5432` |
    | `POSTGRES_HISTORY_USERNAME` | Username      | `chat_history`       |
    | `POSTGRES_HISTORY_PASSWORD` | Password      | -                    |
    | `POSTGRES_HISTORY_DATABASE` | Database name | `chat_history`       |
  </Tab>
</Tabs>

***

### Observability (optional)

#### FlowX Observatory

| Environment Variable        | Description                                   | Default Value               |
| --------------------------- | --------------------------------------------- | --------------------------- |
| `USE_OBSERVATORY`           | Enable Observatory middleware (`1` to enable) | `0`                         |
| `FLOWX_OBSERVATORY_API_URL` | Observatory API URL                           | `http://observatory-api:80` |
| `FLOWX_OBSERVATORY_APP_ID`  | Application ID for Observatory                | -                           |
| `FLOWX_OBSERVATORY_VERBOSE` | Verbose Observatory logging                   | `0`                         |

#### Langfuse

| Environment Variable  | Description         | Default Value |
| --------------------- | ------------------- | ------------- |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | -             |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key | -             |
| `LANGFUSE_HOST`       | Langfuse server URL | -             |

#### LLM Guard

| Environment Variable | Description          | Default Value          |
| -------------------- | -------------------- | ---------------------- |
| `FLOWX_LLMGUARD_URL` | LLMGuard service URL | `http://llmguard:8000` |

***

### CORS configuration

| Environment Variable                 | Description                       | Default Value                           |
| ------------------------------------ | --------------------------------- | --------------------------------------- |
| `APPLICATION_CORS_ALLOWORIGIN`       | Allowed origins (comma-separated) | -                                       |
| `APPLICATION_CORS_ALLOW_HEADERS`     | Allowed headers                   | `Accept,Content-Type,Authorization,...` |
| `APPLICATION_CORS_ALLOW_METHODS`     | Allowed methods                   | `GET,PUT,POST,DELETE,PATCH,OPTIONS`     |
| `APPLICATION_CORS_ALLOW_CREDENTIALS` | Allow credentials                 | `true`                                  |

***

### MCP server configuration

| Environment Variable | Description                                 | Default Value |
| -------------------- | ------------------------------------------- | ------------- |
| `MCP_AUTH_KEY`       | Authentication key for MCP server endpoints | -             |

***

## Kafka job processing

The Web Crawler processes crawl requests asynchronously via Kafka. Integration Designer sends requests to the job request topic, and the Web Crawler writes results to S3 and sends a response to the job response topic.

### Request payload

| Field               | Type       | Default      | Description                                  |
| ------------------- | ---------- | ------------ | -------------------------------------------- |
| `urls`              | `string[]` | *(required)* | URLs to crawl                                |
| `depth`             | `int`      | `1`          | Crawl depth (1 = single page)                |
| `maxPages`          | `int`      | `50`         | Max total pages to crawl                     |
| `maxPagesPerLevel`  | `int`      | `10`         | Max pages per depth level                    |
| `followLinks`       | `bool`     | `true`       | Follow links on crawled pages                |
| `processLinkedPdfs` | `bool`     | `true`       | Process linked PDF documents                 |
| `acceptDownloads`   | `bool`     | `false`      | Download files and upload to Document Plugin |
| `pageTimeout`       | `int`      | `30000`      | Page navigation timeout (ms)                 |
| `proxyUrl`          | `string`   | `null`       | Proxy URL for requests                       |
| `applicationId`     | `string`   | `null`       | Application ID (required for file uploads)   |

### Response flow

1. Integration Designer publishes a crawl request to `ai.flowx.web-crawler.job.request`
2. Web Crawler processes the request and stores the result (Markdown content) in S3
3. Web Crawler publishes a response with the result path to `ai.flowx.web-crawler.job.response`
4. Integration Designer retrieves the result from S3

***

## Deployment and sizing

### Docker

* Base image: Python 3.13-slim-bookworm
* Runs as non-root user (`aiservices`)
* Port: `8080`
* Health check: `/web-crawler/api/v1/web-crawler/info/health`

### Kubernetes configuration

| Setting            | Value   |
| ------------------ | ------- |
| Replicas           | 2       |
| CPU requests       | 1 core  |
| CPU limits         | 2 cores |
| RAM requests       | 1 Gi    |
| RAM limits         | 2 Gi    |
| `GUNICORN_WORKERS` | `1`     |

<Warning>
  The Web Crawler runs headless Chromium browsers for page rendering. Each concurrent crawl consumes significant memory. Monitor memory usage and increase limits if pods are OOM-killed during deep crawls.
</Warning>

***

## Verify your setup

<Check>
  The Web Crawler pod is running: `kubectl get pods -l app=web-crawler`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://web-crawler:8080/web-crawler/api/v1/web-crawler/info/health`
</Check>

<Check>
  Kafka consumer is connected — check pod logs for `Kafka consumer started` message at startup
</Check>

<Check>
  Integration Designer can reach the Web Crawler — verify `FLOWX_WEBCRAWLER_BASEURL` is set in [Integration Designer setup](/5.9/setup-guides/integration-designer-setup)
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pod fails to start or crashes">
    **Symptoms:** Pod stays in CrashLoopBackOff or never becomes ready.

    **Solutions:**

    * Verify Chromium/Playwright dependencies are available (included in Docker image)
    * Check that Kafka broker addresses are reachable
    * Ensure the Keycloak server URL is correct and accessible
    * Review pod logs for specific startup errors
  </Accordion>

  <Accordion title="Crawl jobs not being processed">
    **Symptoms:** Integration Designer sends crawl requests but no results are returned.

    **Solutions:**

    * Verify `KAFKA_CONSUMER_ENABLED` is set to `1`
    * Check that `KAFKA_JOB_REQUEST_TOPIC` matches the topic Integration Designer publishes to
    * Ensure the Kafka consumer group (`KAFKA_CONSUMER_GROUPID`) has no conflicting consumers
    * Review pod logs for Kafka connection or authentication errors
  </Accordion>

  <Accordion title="Crawl results are empty or incomplete">
    **Symptoms:** Pages return no content or partial Markdown.

    **Solutions:**

    * Increase `pageTimeout` in the crawl request for slow-loading pages
    * Check if the target site blocks headless browsers (try configuring a `proxyUrl`)
    * Verify network connectivity from the pod to the target URLs
    * Review verbose logs (`VERBOSE=1`) for page-level errors
  </Accordion>

  <Accordion title="File downloads not uploading">
    **Symptoms:** `acceptDownloads` is enabled but files are not appearing in the Document Plugin.

    **Solutions:**

    * Verify `DOCUMENT_PLUGIN_URL` is set and reachable
    * Ensure `applicationId` is provided in the crawl request payload
    * Check service account credentials (`SERVICE_OAUTH_CLIENT_ID` / `SERVICE_OAUTH_CLIENT_SECRET`)
    * Review pod logs for upload errors or authentication failures
  </Accordion>

  <Accordion title="OOM kills during deep crawls">
    **Symptoms:** Pods restart with OOMKilled status during multi-page crawls.

    **Solutions:**

    * Increase memory limits (try 4 Gi)
    * Reduce `maxPages` and `maxPagesPerLevel` in crawl requests
    * Reduce `GUNICORN_WORKERS` to limit concurrent browser instances
    * Scale horizontally with more pods instead of larger pods
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Integration Designer setup" icon="pencil" href="./integration-designer-setup">
    Configure Integration Designer, which orchestrates Web Crawler jobs
  </Card>

  <Card title="Integration Designer" icon="pencil" href="../docs/platform-deep-dive/integrations/integration-designer">
    Learn about building integration workflows
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="Document Plugin setup" icon="file" href="./documents-plugin-setup">
    Configure the Document Plugin for file storage
  </Card>
</CardGroup>


# Webhook Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/webhook-gateway-setup

Set up the Webhook Gateway microservice — the public endpoint that receives incoming webhook calls from external systems and routes them to FlowX processes via Kafka.

## Dependencies

Before setting up the Webhook Gateway, ensure you have the following dependencies in place:

* **PostgreSQL** database for storing webhook registration data
* **Kafka** for publishing process start events
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization

## Infrastructure prerequisites

| Component  | Description                                    |
| ---------- | ---------------------------------------------- |
| PostgreSQL | Dedicated database named `webhook_gateway`     |
| Kafka      | Message broker for triggering process starts   |
| Keycloak   | Identity provider for service authentication   |
| SpiceDB    | Authorization service for workspace validation |

***

## Configuration

### Authorization configuration

The Webhook Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                                                                                   |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                                                                                    |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002`                                                             |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-webhook-gateway-sa`                                                                         |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

<Info>
  The Webhook Gateway exposes `/webhooks/**` as public (unauthenticated) paths for receiving incoming webhooks. The `/api/**` paths require a valid JWT token.
</Info>

***

### PostgreSQL configuration

The Webhook Gateway uses its own dedicated PostgreSQL database for storing webhook registration data.

| Environment Variable         | Description                        | Default Value                                       |
| ---------------------------- | ---------------------------------- | --------------------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/webhook_gateway` |
| `SPRING_DATASOURCE_USERNAME` | Database username                  | `flowx`                                             |
| `SPRING_DATASOURCE_PASSWORD` | Database password                  | -                                                   |

<Warning>
  Ensure the `webhook_gateway` database is created before deploying the service. The Webhook Gateway will manage its own schema migrations via Liquibase.
</Warning>

***

### Kafka configuration

The Webhook Gateway is a **producer-only** service — it publishes messages to Kafka but does not consume from any topics. It publishes to two topics: one for starting new processes and one for resuming waiting process instances.

#### Core Kafka settings

| Environment Variable               | Description                                             | Default Value    |
| ---------------------------------- | ------------------------------------------------------- | ---------------- |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS`   | Address of the Kafka server(s)                          | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL`   | Security protocol for Kafka connections                 | `PLAINTEXT`      |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10`             |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Topic naming configuration

| Environment Variable             | Description                         | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Package prefix for topic names      | `ai.flowx.`   |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` `           |
| `KAFKA_TOPIC_NAMING_VERSION`     | Version suffix for topic names      | `.v1`         |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator for topic names   | `.`           |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator for topic names | `-`           |

#### Kafka topics

The Webhook Gateway publishes to the following Kafka topics:

| Environment Variable                | Description                                                                                         | Default Value                                      |
| ----------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `KAFKA_TOPIC_PROCESS_START_OUT`     | Topic for triggering process starts from webhook events (Message Start Event)                       | `ai.flowx.core.trigger.start-for-event.process.v1` |
| `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` | Topic for resuming running process instances from webhook events (Message Catch Intermediate Event) | `ai.flowx.core.message.event.process.v1`           |

***

### CAS lib configuration (SpiceDB)

| Environment Variable                         | Description                                                                                                                                                                             | Default Value |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`                         | SpiceDB hostname                                                                                                                                                                        | `spicedb`     |
| `FLOWX_SPICEDB_PORT`                         | SpiceDB gRPC port                                                                                                                                                                       | `50051`       |
| `FLOWX_SPICEDB_TOKEN`                        | SpiceDB authentication token                                                                                                                                                            | -             |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM`      |

***

### Service communication

The Webhook Gateway communicates with the following FlowX services:

| Environment Variable                                       | Description                   | Default Value                    |
| ---------------------------------------------------------- | ----------------------------- | -------------------------------- |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`  | Organization Manager base URL | `http://organization-manager:80` |
| `FLOWX_LIB_CASCLIENT_SERVICES_AUTHORIZATIONSYSTEM_BASEURL` | Authorization System base URL | `http://authorization-system:80` |

***

### Logging configuration

| Environment Variable | Description                    | Default Value |
| -------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT` | Root logging level             | `INFO`        |
| `LOGGING_LEVEL_APP`  | Application-specific log level | `INFO`        |

***

## Secrets management

The Webhook Gateway requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name                                                            | Description                                |
| ---------------------------------------------------------------------- | ------------------------------------------ |
| `SPRING_DATASOURCE_PASSWORD`                                           | PostgreSQL database password               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret            |
| `FLOWX_SPICEDB_TOKEN`                                                  | SpiceDB authentication token               |
| `KAFKA_OAUTH_CLIENT_SECRET`                                            | Kafka OAuth client secret (if using OAuth) |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the Webhook Gateway:

```yaml theme={"system"}
fullnameOverride: webhook-gateway

image:
  repository: <your-registry>/webhook-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/webhook_gateway
  SPRING_DATASOURCE_USERNAME: flowx

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # OAuth2
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakWebhookGatewayClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: true
  admin:
    enabled: true
    path: /webhooks

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/routing-name: "webhook-gateway"
  flowx.ai/prometheus-scrape: "webhook-gateway"
```

<Info>
  Unlike most FlowX services, the Webhook Gateway requires ingress to be enabled because it receives incoming HTTP requests from external systems on the `/webhooks` path.
</Info>

### Network policies

The Webhook Gateway requires network access to the following services:

| Service              | Purpose                         | Pod Label                                |
| -------------------- | ------------------------------- | ---------------------------------------- |
| Kafka                | Message broker communication    | `flowx.ai/egress-s-kafka`                |
| PostgreSQL           | Webhook registration storage    | `flowx.ai/egress-s-postgresql`           |
| Keycloak             | Authentication                  | `flowx.ai/egress-s-keycloak`             |
| SpiceDB              | Authorization                   | `flowx.ai/egress-s-spicedb`              |
| Organization Manager | Organization context resolution | `flowx.ai/egress-s-organization-manager` |
| Authorization System | Access control                  | `flowx.ai/egress-s-authorization-system` |

***

## Monitoring

The Webhook Gateway exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

```yaml theme={"system"}
podLabels:
  flowx.ai/prometheus-scrape: "webhook-gateway"
```

### Health endpoints

| Endpoint            | Description                 |
| ------------------- | --------------------------- |
| `/actuator/health`  | Health check endpoint       |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info`    | App info endpoint           |

***

## Verify your setup

<Check>
  The Webhook Gateway pod is running and healthy: `kubectl get pods -l app=webhook-gateway`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://webhook-gateway:8080/actuator/health`
</Check>

<Check>
  Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`
</Check>

<Check>
  SpiceDB connection is established — check pod logs for successful CAS client initialization
</Check>

<Check>
  The `/webhooks` ingress path is accessible from external systems
</Check>

***

## Ingress and CORS

The Webhook Gateway is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. The path is preserved end-to-end (no rewrite), because the webhook endpoint URL is the same on the backend as on the client.

### Service route

| Host group | External path | Backend receives | Notes          |
| ---------- | ------------- | ---------------- | -------------- |
| admin      | `/webhooks`   | `/webhooks/...`  | Path preserved |

The path is set through `services.webhook-gateway.ingress.admin.path` (or `services.webhook-gateway.gateway.admin.paths`) in the chart values. No rewrite is applied — webhook URLs your upstream systems POST to must match the path exactly.

### CORS configuration

| Environment Variable           | Description                                                                                                                                                                                                                       | Default Value |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Most webhook traffic is server-to-server and unaffected; set this only if a Designer or integration UI calls the Webhook Gateway from the browser. | `-`           |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection failures">
    **Symptoms:** Service fails to start with database connection errors.

    **Solutions:**

    1. Verify the `webhook_gateway` database exists in PostgreSQL
    2. Check that the database user has appropriate permissions
    3. Ensure network connectivity between the pod and PostgreSQL service
    4. Verify the JDBC URL format is correct
  </Accordion>

  <Accordion title="SpiceDB connection failures">
    **Symptoms:** Authorization errors or service fails to initialize CAS client.

    **Solutions:**

    1. Verify SpiceDB is running and reachable at the configured host and port
    2. Check that the SpiceDB token is correct
    3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
    4. Review pod logs for specific CAS client error messages
  </Accordion>

  <Accordion title="Kafka publishing failures">
    **Symptoms:** Webhook events not triggering process starts.

    **Solutions:**

    1. Verify Kafka bootstrap servers are reachable
    2. Check that the `ai.flowx.core.trigger.start-for-event.process.v1` topic exists
    3. Ensure the service has producer permissions on the topic
    4. Review pod logs for Kafka producer errors
  </Accordion>

  <Accordion title="Webhook endpoint not reachable">
    **Symptoms:** External systems cannot reach the webhook URL.

    **Solutions:**

    1. Verify ingress is enabled and the `/webhooks` path is configured
    2. Check that network policies allow inbound traffic to the Webhook Gateway
    3. Ensure DNS resolves correctly for the webhook URL
    4. Verify the service is listening on port `8080`
  </Accordion>

  <Accordion title="Service account authentication errors">
    **Symptoms:** 401/403 errors when communicating with other FlowX services.

    **Solutions:**

    1. Verify the Keycloak service account is properly configured
    2. Check that client secrets match between configuration and Keycloak
    3. Ensure the service account has required roles assigned
    4. Verify `SECURITY_TYPE` is set to `jwt-public-key`
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="SpiceDB Configuration" icon="shield-halved" href="./spicedb">
    Fine-grained authorization setup
  </Card>

  <Card title="Kafka Authentication" icon="lock" href="./kafka-authentication-config">
    Configure Kafka security and authentication
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>
</CardGroup>


# Release Notes
Source: https://docs.flowx.ai/release-notes/overview



🚀 Welcome to FlowX.AI Release Notes.

Stay updated with the latest features and improvements. Follow the Release Notes space to discover what's happening in the FlowX.AI world and the exciting updates we have for you.

<Info>
  **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. Currently, **versions 4.7.x, 5.1.x, and 5.9.x** are our LTS releases, recommended for production environments requiring stability and long-term support.
</Info>

<CardGroup>
  <Card title="Version 5.9.0 LTS" href="./v5.x/v5.9.0-june-2026/v5.9.0-june-2026" icon="shield">
    🚀 Introducing Release 5.9.0, the first release of the 5.9.x LTS line - Released on **June 2nd, 2026**
  </Card>

  <Card title="Version 5.1.9 LTS" href="./v5.x/v5.1.x-lts/v5.1.9-may-2026" icon="shield">
    🛡️ **LTS Release** 5.1.9 - Released on **May 29th, 2026**
  </Card>

  <Card title="Version 5.8.0" href="./v5.x/v5.8.0-may-2026/v5.8.0-may-2026" icon="scroll">
    🚀 Introducing Release 5.8.0 - Released on **May 10th, 2026**
  </Card>

  <Card title="Version 5.1.8 LTS" href="./v5.x/v5.1.x-lts/v5.1.8-april-2026" icon="shield">
    🛡️ **LTS Release** 5.1.8 - Released on **April 30th, 2026**
  </Card>

  <Card title="Version 5.7.0" href="./v5.x/v5.7.0-april-2026/v5.7.0-april-2026" icon="scroll">
    🚀 Introducing Release 5.7.0 - Released on **April 28th, 2026**
  </Card>

  <Card title="Version 5.6.0" href="./v5.x/v5.6.0-march-2026/v5.6.0-march-2026" icon="scroll">
    🚀 Introducing Release 5.6.0 - Released on **March 25th, 2026**
  </Card>

  <Card title="Version 5.1.7 LTS" href="./v5.x/v5.1.x-lts/v5.1.7-march-2026" icon="shield">
    🛡️ **LTS Release** 5.1.7 - Released on **March 26th, 2026**
  </Card>

  <Card title="Version 5.1.6 LTS" href="./v5.x/v5.1.x-lts/v5.1.6-march-2026" icon="shield">
    🛡️ **LTS Release** 5.1.6 - Released on **March 16th, 2026**
  </Card>

  <Card title="Version 5.5.0" href="./v5.x/v5.5.0-february-2026/v5.5.0-february-2026" icon="scroll">
    🚀 Introducing Release 5.5.0 - Released on **February 27th, 2026**
  </Card>

  <Card title="Version 5.1.5 LTS" href="./v5.x/v5.1.x-lts/v5.1.5-february-2026" icon="shield">
    🛡️ **LTS Release** 5.1.5 - Released on **February 27th, 2026**
  </Card>

  <Card title="Version 5.1.4 LTS" href="./v5.x/v5.1.x-lts/v5.1.4-february-2026" icon="shield">
    🛡️ **LTS Release** 5.1.4 - Released on **February 9th, 2026**
  </Card>

  <Card title="Version 5.4.0" href="./v5.x/v5.4.0-january-2026/v5.4.0-january-2026" icon="scroll">
    🚀 Introducing Release 5.4.0 - Released on **January 30th, 2026**
  </Card>

  <Card title="Version 5.1.3 LTS" href="./v5.x/v5.1.x-lts/v5.1.3-january-2026" icon="shield">
    🛡️ **LTS Release** 5.1.3 - Released on **January 15th, 2026**
  </Card>

  <Card title="Version 5.3.0" href="./v5.x/v5.3.0-december-2025/v5.3.0-december-2025" icon="scroll">
    🚀 Introducing Release 5.3.0 - Released on **December 24th, 2025**
  </Card>

  <Card title="Version 5.1.2 LTS" href="./v5.x/v5.1.x-lts/v5.1.2-december-2025" icon="shield">
    🛡️ **LTS Release** 5.1.2 - Released on **December 3rd, 2025**
  </Card>

  <Card title="Version 5.2.0" href="./v5.x/v5.2.0-november-2025/v5.2.0-november-2025" icon="scroll">
    🚀 Introducing Release 5.2.0 - Released on **November 10th, 2025**
  </Card>

  <Card title="Version 5.1.1 LTS" href="./v5.x/v5.1.x-lts/v5.1.1-november-2025" icon="shield">
    🛡️ **LTS Release** 5.1.1 - Released on **November 10th, 2025**
  </Card>

  <Card title="Version 4.7.11 LTS" href="./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025" icon="shield">
    🛡️ **LTS Release** 4.7.11 - Released on **December 16th, 2025**
  </Card>

  <Card title="Version 4.7.10 LTS" href="./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025" icon="shield">
    🛡️ **LTS Release** 4.7.10 - Released on **November 17th, 2025**
  </Card>

  <Card title="Version 4.7.9 LTS" href="./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025" icon="shield">
    🛡️ **LTS Release** 4.7.9 - Released on **October 16th, 2025**
  </Card>

  <Card title="Version 5.1.0 LTS" href="./v5.x/v5.1.x-lts/v5.1.0-september-2025/v5.1.0-september-2025" icon="shield">
    🛡️ **LTS Release** 5.1.0 - Released on **October 2nd, 2025**
  </Card>

  <Card title="Version 4.7.8 LTS" href="./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025" icon="shield">
    🛡️ **LTS Release** 4.7.8 - Released on **September 16th, 2025**
  </Card>

  <Card title="Version 4.7.7 LTS" href="./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025" icon="shield">
    🛡️ **LTS Release** 4.7.7 - Released on **August 20th, 2025**
  </Card>

  <Card title="Version 5.0.0" href="./v5.x/v5.0.0-july-2025/v5.0.0-july-2025" icon="scroll">
    🚀 Introducing Release 5.0.0 - Released on **July 31st, 2025**
  </Card>

  <Card title="Version 4.7.6 LTS" href="./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025" icon="shield">
    🛡️ **LTS Release** 4.7.6 - Released on **July 18th, 2025**
  </Card>

  <Card title="Version 4.7.5 LTS" href="./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025" icon="shield">
    🛡️ **LTS Release** 4.7.5 - Released on **June 19th, 2025**
  </Card>

  <Card title="Version 4.7.4 LTS" href="./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025" icon="shield">
    🛡️ **LTS Release** 4.7.4 - Released on **May 15th, 2025**
  </Card>

  <Card title="Version 4.7.3 LTS" href="./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025" icon="shield">
    🛡️ **LTS Release** 4.7.3 - Released on **April 14th, 2025**
  </Card>

  <Card title="Version 4.7.2 LTS" href="./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025" icon="shield">
    🛡️ **LTS Release** 4.7.2 - Released on **March 26th, 2025**
  </Card>

  <Card title="Version 4.7.1 LTS" href="./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025" icon="shield">
    🛡️ **LTS Release** 4.7.1 - Released on **March 7th, 2025**
  </Card>

  <Card title="Version 4.7.0 LTS" href="./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025" icon="shield">
    🛡️ **LTS Release** 4.7.0 - Released on **February 24th, 2025**
  </Card>

  <Card title="Version 4.6.1" href="./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025" icon="scroll">
    🚀 Introducing Release 4.6.1 - Released on **February 7th, 2025**
  </Card>

  <Card title="Version 4.6.0" href="./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025" icon="scroll">
    🚀 Introducing Release 4.6.0 - Released on **January 23rd, 2025**
  </Card>

  <Card title="Version 4.1.5 LTS" href="./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024" icon="shield">
    🛡️ **LTS Release** 4.1.5 - Released on **September 23rd, 2024**
  </Card>

  <Card title="Version 4.1.4 LTS" href="./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024" icon="shield">
    🛡️ **LTS Release** 4.1.4 - Released on **September 6th, 2024**
  </Card>

  <Card title="Version 4.1.3 LTS" href="./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024" icon="shield">
    🛡️ **LTS Release** 4.1.3 - Released on **August 12th, 2024**
  </Card>

  <Card title="Version 4.1.2 LTS" href="./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024" icon="shield">
    🛡️ **LTS Release** 4.1.2 - Released on **June 8th, 2024**
  </Card>

  <Card title="Version 4.1.1 LTS" href="./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024" icon="shield">
    🛡️ **LTS Release** 4.1.1 - Released on **June 17th, 2024**
  </Card>

  <Card title="Version 4.1.0 LTS" href="./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024" icon="shield">
    🛡️ **LTS Release** 4.1.0 - Released on **May 30th, 2024**
  </Card>

  <Card title="Version 4.0.0" href="./v4.x/v4.0.0-april-2024/v4.0.0-april-2024" icon="scroll">
    🚀 Introducing Release 4.0.0 - Released on **April 18th, 2024**
  </Card>
</CardGroup>

***

<Accordion title="Version 3.x.x" icon="files">
  <CardGroup>
    <Card title="v3.4.8 - June 2024" href="/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024">
      Explore the latest enhancements and fixes introduced in June 2024.
    </Card>

    <Card title="v3.4.7 - January 2024" href="/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024">
      Explore the latest enhancements and fixes introduced in January 2024.
    </Card>

    <Card title="v3.4.6 - December 2023" href="/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023">
      Explore the latest enhancements and fixes introduced in December 2023.
    </Card>

    <Card title="v3.4.5 - November 2023" href="/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023">
      Explore the latest enhancements and fixes introduced in November 2023.
    </Card>

    <Card title="v3.4.4 - November 2023" href="/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023">
      Discover the significant changes and improvements made in November 2023.
    </Card>

    <Card title="v3.4.3 - October 2023" href="/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023">
      Discover the significant changes and improvements made in October 2023.
    </Card>

    <Card title="v3.4.2 - October 2023" href="/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023">
      Discover the significant changes and improvements made in October 2023.
    </Card>

    <Card title="v3.4.1 - September 2023" href="/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023">
      Discover the significant changes and improvements made in September 2023.
    </Card>

    <Card title="v3.4.0 - September 2023" href="/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023">
      Discover the significant changes and improvements made in September 2023.
    </Card>

    <Card title="v3.3.0 - July 2023" href="/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023">
      Discover the significant changes and improvements made in July 2023.
    </Card>

    <Card title="v3.2.0 - April 2023" href="/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023">
      Discover the significant changes and improvements made in April 2023.
    </Card>

    <Card title="v3.1.0 - March 2023" href="/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023">
      Discover the significant changes and improvements made in March 2023.
    </Card>

    <Card title="v3.0.0 - February 2023" href="/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023">
      Discover the significant changes and improvements made in February 2023.
    </Card>
  </CardGroup>
</Accordion>


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

<Card title="Upgrade Path" icon="route">
  **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.1       | 5.1.0   | 5.0.0  | 4.7.9   | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5   |
| -------------------------- | ----------- | ------- | ------ | ------- | ------ | ------ | ------ | ------- |
| **process-engine**         | **9.64.3**  | 9.63.0  | 9.29.2 | 8.24.1  | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin**                  | **9.66.5**  | 9.65.0  | 9.25.2 | 7.18.4  | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2  |
| **designer**               | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1  |
| **cms-core**               | **9.36.3**  | 9.35.0  | 9.21.2 | 5.11.1  | 5.10.3 | 5.9.2  | 5.8.2  | 5.5.1   |
| **scheduler-core**         | **9.26.1**  | 9.25.0  | 9.12.0 | 5.7.1   | 5.6.2  | 5.5.2  | 5.4.0  | 5.1.1   |
| **events-gateway**         | **9.26.1**  | 9.25.0  | 9.12.0 | 5.7.1   | 5.6.2  | 5.5.2  | 5.4.0  | 5.1.1   |
| **notification-plugin**    | **9.29.1**  | 9.28.0  | 9.14.2 | 6.8.1   | 6.7.2  | 6.6.2  | 6.5.0  | 6.2.1   |
| **document-plugin**        | **9.35.1**  | 9.34.0  | 9.17.2 | 6.10.1  | 6.9.2  | 6.8.2  | 6.7.0  | 6.4.1   |
| **task-management-plugin** | **9.34.2**  | 9.33.0  | 9.14.2 | 7.9.2   | 7.8.2  | 7.7.2  | 7.6.0  | 7.3.1   |
| **data-search**            | **9.23.1**  | 9.22.0  | 9.12.1 | 4.7.1   | 4.6.2  | 4.5.2  | 4.4.0  | 4.1.1   |
| **audit-core**             | **9.30.1**  | 9.29.1  | 9.15.2 | 6.8.1   | 6.7.2  | 6.6.2  | 6.5.0  | 6.1.1   |
| **advancing-controller**   | **9.25.1**  | 9.24.0  | 9.11.0 | 4.7.1   | 4.6.2  | 4.6.2  | 4.4.0  | 4.1.1   |
| **integration-designer**   | **9.50.0**  | 9.49.1  | 9.26.2 | 2.16.1  | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0   |
| **application-manager**    | **9.73.6**  | 9.72.0  | 9.27.3 | 2.23.1  | 2.22.3 | 2.21.2 | 2.2    |         |
| **runtime-manager**        | **9.73.6**  | 9.72.0  | 9.27.3 | 2.23.1  | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2  |
| **data-sync**              | **9.22.1**  | 9.21.0  | 9.11.0 | 2.10.2  | 2.9.2  | 2.8.1  | 2.7.1  | 2.4.1   |
| **authorization-system**   | **9.34.2**  | 9.33.0  | 9.14.2 | -       | -      | -      | -      | -       |
| **nosql-db-runner**        | **9.22.1**  | 9.21.0  | 9.11.0 | -       | -      | -      | -      | -       |

### Renderers

| Component                     | 5.1.1       | 5.1.0   | 5.0.0  | 4.7.9   | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  |
| ----------------------------- | ----------- | ------- | ------ | ------- | ------ | ------ | ------ | ------ |
| **@flowx/angular-sdk**        | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme**      | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk**          | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme**        | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit**   | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk**           | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme**         | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer**              | **9.0.5**   | 9.0.4   | 9.0.0  | 4.0.29  | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer**          | **9.0.3**   | 9.0.2   | 9.0.0  | 4.0.29  | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component            | 5.1.1  | 5.1.0  | 5.0.0  | 4.7.9  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  |

### AI Platform

| Component                       | 5.1.1     | 5.1.0 | 5.0.0  | 4.7.9  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  |
| ------------------------------- | --------- | ----- | ------ | ------ | ------ | ------ | ------ | ------ |
| **ai-assistant**                | **9.2.5** | 9.2.4 | 9.2.3  | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform**                 | 9.3.1     | 9.3.1 | 9.0.12 | 1.4.6  | 1.4.6  | 1.4.5  | 1.4.5  | 1.4.3  |
| **ai-platform-ai-developer**    | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-agents**          | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-conversations**   | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-models**          | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-tenants**         | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-planner**         | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-ai-analyst**      | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-ai-designer**     | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-agent-builder**   | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-binaries**        | **9.4.2** | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

<Check>
  No environment variable changes\
  No database migrations\
  No breaking changes\
  Compatible with existing 5.1.0 processes and configurations
</Check>

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.1            | Keycloak             | 26+                |
| 5.1.2            | Kafka                | 3.8 - 3.9          |
| 5.1.1            | PostgreSQL           | 16 - 17            |
| 5.1.1            | Oracle Database      | 21c, 23ai          |
| 5.1.1            | MongoDB              | 7 - 8              |
| 5.1.1            | Redis                | 7.4 - 8.0          |
| 5.1.1            | Elasticsearch        | 8                  |
| 5.1.1            | Angular (Web SDK)    | 19.x               |
| 5.1.1            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

<Card title="Upgrade Path" icon="route">
  **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.2       | 5.1.1   | 5.1.0   | 5.0.0  |
| -------------------------- | ----------- | ------- | ------- | ------ |
| **process-engine**         | **9.67.0**  | 9.64.3  | 9.63.0  | 9.29.2 |
| **admin**                  | **9.68.1**  | 9.66.5  | 9.65.0  | 9.25.2 |
| **designer**               | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core**               | **9.39.0**  | 9.36.3  | 9.35.0  | 9.21.2 |
| **scheduler-core**         | **9.28.1**  | 9.26.1  | 9.25.0  | 9.12.0 |
| **events-gateway**         | **9.29.0**  | 9.26.1  | 9.25.0  | 9.12.0 |
| **notification-plugin**    | **9.32.0**  | 9.29.1  | 9.28.0  | 9.14.2 |
| **document-plugin**        | **9.37.1**  | 9.35.1  | 9.34.0  | 9.17.2 |
| **task-management-plugin** | **9.36.1**  | 9.34.2  | 9.33.0  | 9.14.2 |
| **data-search**            | **9.25.1**  | 9.23.1  | 9.22.0  | 9.12.1 |
| **audit-core**             | **9.33.0**  | 9.30.1  | 9.29.1  | 9.15.2 |
| **advancing-controller**   | **9.28.0**  | 9.25.1  | 9.24.0  | 9.11.0 |
| **integration-designer**   | **9.52.1**  | 9.50.0  | 9.49.1  | 9.26.2 |
| **application-manager**    | **9.75.1**  | 9.73.6  | 9.72.0  | 9.27.3 |
| **runtime-manager**        | **9.75.1**  | 9.73.6  | 9.72.0  | 9.27.3 |
| **data-sync**              | **9.26.0**  | 9.22.1  | 9.21.0  | 9.11.0 |
| **authorization-system**   | **9.36.1**  | 9.34.2  | 9.33.0  | 9.14.2 |
| **nosql-db-runner**        | **9.24.1**  | 9.22.1  | 9.21.0  | 9.11.0 |

### Renderers

| Component                     | 5.1.2       | 5.1.1   | 5.1.0   | 5.0.0  |
| ----------------------------- | ----------- | ------- | ------- | ------ |
| **@flowx/angular-sdk**        | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme**      | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk**          | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme**        | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit**   | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk**           | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme**         | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer**              | **9.0.7**   | 9.0.5   | 9.0.4   | 9.0.0  |
| **Android renderer**          | **9.0.5**   | 9.0.3   | 9.0.2   | 9.0.0  |

### Plugins

| Component            | 5.1.2  | 5.1.1  | 5.1.0  | 5.0.0  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.0  |

### AI Platform

| Component                       | 5.1.2     | 5.1.1 | 5.1.0 | 5.0.0  |
| ------------------------------- | --------- | ----- | ----- | ------ |
| **ai-assistant**                | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3  |
| **di-platform**                 | 9.3.1     | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer**    | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-connected-graph** | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-knowledge-graph** | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-agents**          | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-conversations**   | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-models**          | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-tenants**         | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-planner**         | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-ai-analyst**      | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-ai-designesr**    | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-agent-builder**   | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-binaries**        | 9.4.2     | 9.4.2 | 9.3.0 | 9.0.1  |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

<Check>
  No environment variable changes\
  No database migrations\
  No breaking changes\
  Compatible with existing 5.1.1 processes and configurations
</Check>

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.2            | Keycloak             | 26+                |
| 5.1.2            | Kafka                | 3.8 - 3.9          |
| 5.1.2            | PostgreSQL           | 16 - 17            |
| 5.1.2            | Oracle Database      | 21c, 23ai          |
| 5.1.2            | MongoDB              | 7 - 8              |
| 5.1.2            | Redis                | 7.4 - 8.0          |
| 5.1.2            | Elasticsearch        | 8                  |
| 5.1.2            | Angular (Web SDK)    | 19.x               |
| 5.1.2            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

<Card title="Upgrade Path" icon="route">
  **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.3       | 5.1.2   | 5.1.1   | 5.1.0   |
| -------------------------- | ----------- | ------- | ------- | ------- |
| **process-engine**         | **9.70.1**  | 9.67.0  | 9.64.3  | 9.63.0  |
| **admin**                  | **9.70.2**  | 9.68.1  | 9.66.5  | 9.65.0  |
| **designer**               | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core**               | **9.41.1**  | 9.39.0  | 9.36.3  | 9.35.0  |
| **scheduler-core**         | **9.30.1**  | 9.28.1  | 9.26.1  | 9.25.0  |
| **events-gateway**         | **9.31.2**  | 9.29.0  | 9.26.1  | 9.25.0  |
| **notification-plugin**    | **9.34.1**  | 9.32.0  | 9.29.1  | 9.28.0  |
| **document-plugin**        | **9.39.1**  | 9.37.1  | 9.35.1  | 9.34.0  |
| **task-management-plugin** | **9.38.2**  | 9.36.1  | 9.34.2  | 9.33.0  |
| **data-search**            | **9.27.1**  | 9.25.1  | 9.23.1  | 9.22.0  |
| **audit-core**             | **9.35.1**  | 9.33.0  | 9.30.1  | 9.29.1  |
| **advancing-controller**   | **9.30.2**  | 9.28.0  | 9.25.1  | 9.24.0  |
| **integration-designer**   | **9.54.1**  | 9.52.1  | 9.50.0  | 9.49.1  |
| **application-manager**    | **9.77.2**  | 9.75.1  | 9.73.6  | 9.72.0  |
| **runtime-manager**        | **9.77.2**  | 9.75.1  | 9.73.6  | 9.72.0  |
| **data-sync**              | **9.28.1**  | 9.26.0  | 9.22.1  | 9.21.0  |
| **authorization-system**   | **9.38.1**  | 9.36.1  | 9.34.2  | 9.33.0  |
| **nosql-db-runner**        | **9.26.1**  | 9.24.1  | 9.22.1  | 9.21.0  |

### Renderers

| Component                     | 5.1.3       | 5.1.2   | 5.1.1   | 5.1.0   |
| ----------------------------- | ----------- | ------- | ------- | ------- |
| **@flowx/angular-sdk**        | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme**      | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk**          | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme**        | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit**   | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk**           | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme**         | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer**              | **9.0.8**   | 9.0.7   | 9.0.5   | 9.0.4   |
| **Android renderer**          | **9.0.6**   | 9.0.5   | 9.0.3   | 9.0.2   |

### Plugins

| Component            | 5.1.3  | 5.1.2  | 5.1.1  | 5.1.0  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.3     | 5.1.2 | 5.1.1 | 5.1.0 |
| ------------------------------- | --------- | ----- | ----- | ----- |
| **ai-assistant**                | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform**                 | 9.3.1     | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents**          | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations**   | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models**          | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants**         | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner**         | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst**      | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer**     | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder**   | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries**        | 9.4.2     | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

<Check>
  No environment variable changes required\
  No database migrations\
  No breaking changes\
  Compatible with existing 5.1.2 processes and configurations
</Check>

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable                        | Description                                                                     | Default                             |
| ------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------- |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

<Info>
  This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.
</Info>

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.3            | Keycloak             | 26+                |
| 5.1.3            | Kafka                | 3.8 - 3.9          |
| 5.1.3            | PostgreSQL           | 16 - 17            |
| 5.1.3            | Oracle Database      | 21c, 23ai          |
| 5.1.3            | MongoDB              | 7 - 8              |
| 5.1.3            | Redis                | 7.4 - 8.0          |
| 5.1.3            | Elasticsearch        | 8                  |
| 5.1.3            | Angular (Web SDK)    | 19.2               |
| 5.1.3            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

<Card title="Upgrade Path" icon="route">
  **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.4       | 5.1.3   | 5.1.2   | 5.1.1   |
| -------------------------- | ----------- | ------- | ------- | ------- |
| **process-engine**         | **9.72.2**  | 9.70.1  | 9.67.0  | 9.64.3  |
| **admin**                  | **9.72.0**  | 9.70.2  | 9.68.1  | 9.66.5  |
| **designer**               | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core**               | **9.43.1**  | 9.41.1  | 9.39.0  | 9.36.3  |
| **scheduler-core**         | **9.32.0**  | 9.30.1  | 9.28.1  | 9.26.1  |
| **events-gateway**         | **9.33.0**  | 9.31.2  | 9.29.0  | 9.26.1  |
| **notification-plugin**    | **9.36.0**  | 9.34.1  | 9.32.0  | 9.29.1  |
| **document-plugin**        | **9.41.1**  | 9.39.1  | 9.37.1  | 9.35.1  |
| **task-management-plugin** | **9.40.0**  | 9.38.2  | 9.36.1  | 9.34.2  |
| **data-search**            | **9.29.0**  | 9.27.1  | 9.25.1  | 9.23.1  |
| **audit-core**             | **9.37.0**  | 9.35.1  | 9.33.0  | 9.30.1  |
| **advancing-controller**   | **9.32.0**  | 9.30.2  | 9.28.0  | 9.25.1  |
| **integration-designer**   | **9.56.0**  | 9.54.1  | 9.52.1  | 9.50.0  |
| **application-manager**    | **9.79.1**  | 9.77.2  | 9.75.1  | 9.73.6  |
| **runtime-manager**        | **9.79.1**  | 9.77.2  | 9.75.1  | 9.73.6  |
| **data-sync**              | **9.30.1**  | 9.28.1  | 9.26.0  | 9.22.1  |
| **authorization-system**   | **9.40.1**  | 9.38.1  | 9.36.1  | 9.34.2  |
| **nosql-db-runner**        | **9.28.0**  | 9.26.1  | 9.24.1  | 9.22.1  |

### Renderers

| Component                     | 5.1.4       | 5.1.3   | 5.1.2   | 5.1.1   |
| ----------------------------- | ----------- | ------- | ------- | ------- |
| **@flowx/angular-sdk**        | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme**      | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk**          | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme**        | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit**   | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk**           | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme**         | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer**              | **9.0.9**   | 9.0.8   | 9.0.7   | 9.0.5   |
| **Android renderer**          | **9.0.7**   | 9.0.6   | 9.0.5   | 9.0.3   |

### Plugins

| Component            | 5.1.4  | 5.1.3  | 5.1.2  | 5.1.1  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.4     | 5.1.3 | 5.1.2 | 5.1.1 |
| ------------------------------- | --------- | ----- | ----- | ----- |
| **ai-assistant**                | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform**                 | 9.3.1     | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents**          | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations**   | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models**          | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants**         | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner**         | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst**      | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer**     | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder**   | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries**        | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

<Check>
  No required configuration changes
  No database migrations
  No breaking changes
  Compatible with existing 5.1.3 processes and configurations
</Check>

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable                  | Description                                             | Default Value | Component      |
| ------------------------------------- | ------------------------------------------------------- | ------------- | -------------- |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120`         | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache    | `500`         | process-engine |

<Info>
  These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.

  For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
</Info>

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.4            | Keycloak             | 26+                |
| 5.1.4            | Kafka                | 3.8 - 3.9          |
| 5.1.4            | PostgreSQL           | 16 - 17            |
| 5.1.4            | Oracle Database      | 21c, 23ai          |
| 5.1.4            | MongoDB              | 7 - 8              |
| 5.1.4            | Redis                | 7.4 - 8.0          |
| 5.1.4            | Elasticsearch        | 8                  |
| 5.1.4            | Angular (Web SDK)    | 19.2               |
| 5.1.4            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

<Card title="Upgrade Path" icon="route">
  **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.5        | 5.1.4   | 5.1.3   | 5.1.2   |
| -------------------------- | ------------ | ------- | ------- | ------- |
| **process-engine**         | **9.72.5**   | 9.72.2  | 9.70.1  | 9.67.0  |
| **admin**                  | **9.72.2**   | 9.72.0  | 9.70.2  | 9.68.1  |
| **designer**               | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core**               | **9.43.3**   | 9.43.1  | 9.41.1  | 9.39.0  |
| **scheduler-core**         | **9.32.2**   | 9.32.0  | 9.30.1  | 9.28.1  |
| **events-gateway**         | **9.33.2**   | 9.33.0  | 9.31.2  | 9.29.0  |
| **notification-plugin**    | **9.36.2**   | 9.36.0  | 9.34.1  | 9.32.0  |
| **document-plugin**        | **9.41.3**   | 9.41.1  | 9.39.1  | 9.37.1  |
| **task-management-plugin** | **9.40.2**   | 9.40.0  | 9.38.2  | 9.36.1  |
| **data-search**            | **9.29.2**   | 9.29.0  | 9.27.1  | 9.25.1  |
| **audit-core**             | **9.37.2**   | 9.37.0  | 9.35.1  | 9.33.0  |
| **advancing-controller**   | **9.32.1**   | 9.32.0  | 9.30.2  | 9.28.0  |
| **integration-designer**   | **9.56.2**   | 9.56.0  | 9.54.1  | 9.52.1  |
| **application-manager**    | **9.79.3**   | 9.79.1  | 9.77.2  | 9.75.1  |
| **runtime-manager**        | **9.79.3**   | 9.79.1  | 9.77.2  | 9.75.1  |
| **data-sync**              | **9.30.2**   | 9.30.1  | 9.28.1  | 9.26.0  |
| **authorization-system**   | **9.40.2**   | 9.40.1  | 9.38.1  | 9.36.1  |
| **nosql-db-runner**        | **9.28.2**   | 9.28.0  | 9.26.1  | 9.24.1  |

### Renderers

| Component                     | 5.1.5        | 5.1.4   | 5.1.3   | 5.1.2   |
| ----------------------------- | ------------ | ------- | ------- | ------- |
| **@flowx/angular-sdk**        | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme**      | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk**          | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme**        | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit**   | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk**           | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme**         | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer**              | **9.0.10**   | 9.0.9   | 9.0.8   | 9.0.7   |
| **Android renderer**          | 9.0.7        | 9.0.7   | 9.0.6   | 9.0.5   |

### Plugins

| Component            | 5.1.5  | 5.1.4  | 5.1.3  | 5.1.2  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.5     | 5.1.4 | 5.1.3 | 5.1.2 |
| ------------------------------- | --------- | ----- | ----- | ----- |
| **ai-assistant**                | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform**                 | 9.3.1     | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents**          | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations**   | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models**          | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants**         | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner**         | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst**      | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer**     | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder**   | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries**        | 9.4.2     | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

<Check>
  No new environment variables
  No required configuration changes
  No database migrations
  No breaking changes
  Compatible with existing 5.1.4 processes and configurations
</Check>

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.5            | Keycloak             | 26+                |
| 5.1.5            | Kafka                | 3.8 - 3.9          |
| 5.1.5            | PostgreSQL           | 16 - 17            |
| 5.1.5            | Oracle Database      | 21c, 23ai          |
| 5.1.5            | MongoDB              | 7 - 8              |
| 5.1.5            | Redis                | 7.4 - 8.0          |
| 5.1.5            | Elasticsearch        | 8                  |
| 5.1.5            | Angular (Web SDK)    | 19.2               |
| 5.1.5            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

<Card title="Upgrade Path" icon="route">
  **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.6       | 5.1.5    | 5.1.4   | 5.1.3   |
| -------------------------- | ----------- | -------- | ------- | ------- |
| **process-engine**         | **9.72.7**  | 9.72.5   | 9.72.2  | 9.70.1  |
| **admin**                  | **9.72.4**  | 9.72.2   | 9.72.0  | 9.70.2  |
| **designer**               | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core**               | **9.43.5**  | 9.43.3   | 9.43.1  | 9.41.1  |
| **scheduler-core**         | **9.32.4**  | 9.32.2   | 9.32.0  | 9.30.1  |
| **events-gateway**         | **9.33.4**  | 9.33.2   | 9.33.0  | 9.31.2  |
| **notification-plugin**    | **9.36.4**  | 9.36.2   | 9.36.0  | 9.34.1  |
| **document-plugin**        | **9.41.5**  | 9.41.3   | 9.41.1  | 9.39.1  |
| **task-management-plugin** | **9.40.4**  | 9.40.2   | 9.40.0  | 9.38.2  |
| **data-search**            | **9.29.4**  | 9.29.2   | 9.29.0  | 9.27.1  |
| **audit-core**             | **9.37.4**  | 9.37.2   | 9.37.0  | 9.35.1  |
| **advancing-controller**   | **9.32.3**  | 9.32.1   | 9.32.0  | 9.30.2  |
| **integration-designer**   | **9.56.3**  | 9.56.2   | 9.56.0  | 9.54.1  |
| **application-manager**    | **9.79.6**  | 9.79.3   | 9.79.1  | 9.77.2  |
| **runtime-manager**        | **9.79.6**  | 9.79.3   | 9.79.1  | 9.77.2  |
| **data-sync**              | **9.30.4**  | 9.30.2   | 9.30.1  | 9.28.1  |
| **authorization-system**   | **9.40.3**  | 9.40.2   | 9.40.1  | 9.38.1  |
| **nosql-db-runner**        | **9.28.4**  | 9.28.2   | 9.28.0  | 9.26.1  |

### Renderers

| Component                     | 5.1.6       | 5.1.5    | 5.1.4   | 5.1.3   |
| ----------------------------- | ----------- | -------- | ------- | ------- |
| **@flowx/angular-sdk**        | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme**      | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk**          | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme**        | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit**   | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk**           | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme**         | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer**              | **9.0.11**  | 9.0.10   | 9.0.9   | 9.0.8   |
| **Android renderer**          | 9.0.7       | 9.0.7    | 9.0.7   | 9.0.6   |

### Plugins

| Component            | 5.1.6  | 5.1.5  | 5.1.4  | 5.1.3  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| ------------------------------- | ----- | ----- | ----- | ----- |
| **ai-assistant**                | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform**                 | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst**      | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer**     | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries**        | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                                   |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.**                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.**                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

<Info>
  This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.
</Info>

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable        | Description                                                | Default Value | Component      |
| --------------------------- | ---------------------------------------------------------- | ------------- | -------------- |
| `FLOWX_RETRY_MAX_RETRIES`   | Maximum retry attempts (total = max + 1 including initial) | `9`           | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds                      | `10`          | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS`  | Maximum backoff delay cap in milliseconds                  | `200`         | process-engine |

<Check>
  No required configuration changes
  No database migrations
  No breaking changes
  Compatible with existing 5.1.5 processes and configurations
</Check>

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.6            | Keycloak             | 26+                |
| 5.1.6            | Kafka                | 3.8 - 3.9          |
| 5.1.6            | PostgreSQL           | 16 - 17            |
| 5.1.6            | Oracle Database      | 21c, 23ai          |
| 5.1.6            | MongoDB              | 7 - 8              |
| 5.1.6            | Redis                | 7.4 - 8.0          |
| 5.1.6            | Elasticsearch        | 8                  |
| 5.1.6            | Angular (Web SDK)    | 19.2               |
| 5.1.6            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

<Card title="Upgrade Path" icon="route">
  **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.7      | 5.1.6   | 5.1.5    | 5.1.4   |
| -------------------------- | ---------- | ------- | -------- | ------- |
| **process-engine**         | **9.73.1** | 9.72.7  | 9.72.5   | 9.72.2  |
| **admin**                  | **9.73.1** | 9.72.4  | 9.72.2   | 9.72.0  |
| **designer**               | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core**               | **9.44.2** | 9.43.5  | 9.43.3   | 9.43.1  |
| **scheduler-core**         | **9.33.1** | 9.32.4  | 9.32.2   | 9.32.0  |
| **events-gateway**         | **9.34.1** | 9.33.4  | 9.33.2   | 9.33.0  |
| **notification-plugin**    | **9.37.1** | 9.36.4  | 9.36.2   | 9.36.0  |
| **document-plugin**        | **9.42.2** | 9.41.5  | 9.41.3   | 9.41.1  |
| **task-management-plugin** | **9.41.1** | 9.40.4  | 9.40.2   | 9.40.0  |
| **data-search**            | **9.30.1** | 9.29.4  | 9.29.2   | 9.29.0  |
| **audit-core**             | **9.38.1** | 9.37.4  | 9.37.2   | 9.37.0  |
| **advancing-controller**   | **9.33.1** | 9.32.3  | 9.32.1   | 9.32.0  |
| **integration-designer**   | **9.57.1** | 9.56.3  | 9.56.2   | 9.56.0  |
| **application-manager**    | **9.80.2** | 9.79.6  | 9.79.3   | 9.79.1  |
| **runtime-manager**        | **9.80.2** | 9.79.6  | 9.79.3   | 9.79.1  |
| **data-sync**              | **9.31.1** | 9.30.4  | 9.30.2   | 9.30.1  |
| **authorization-system**   | **9.41.1** | 9.40.3  | 9.40.2   | 9.40.1  |
| **nosql-db-runner**        | **9.29.1** | 9.28.4  | 9.28.2   | 9.28.0  |

### Renderers

| Component                     | 5.1.7      | 5.1.6   | 5.1.5    | 5.1.4   |
| ----------------------------- | ---------- | ------- | -------- | ------- |
| **@flowx/angular-sdk**        | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme**      | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk**          | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme**        | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit**   | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk**           | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme**         | 9.164.2    | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer**              | **9.0.12** | 9.0.11  | 9.0.10   | 9.0.9   |
| **Android renderer**          | **9.0.13** | 9.0.7   | 9.0.7    | 9.0.7   |

### Plugins

| Component            | 5.1.7  | 5.1.6  | 5.1.5  | 5.1.4  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| ------------------------------- | ----- | ----- | ----- | ----- |
| **ai-assistant**                | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform**                 | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst**      | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer**     | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries**        | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                                   |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.**                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.**                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

<Info>
  No configuration changes are required for this release.
</Info>

<Check>
  No required configuration changes
  No database migrations
  No breaking changes
  Compatible with existing 5.1.6 processes and configurations
</Check>

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.7            | Keycloak             | 26+                |
| 5.1.7            | Kafka                | 3.8 - 3.9          |
| 5.1.7            | PostgreSQL           | 16 - 17            |
| 5.1.7            | Oracle Database      | 21c, 23ai          |
| 5.1.7            | MongoDB              | 7 - 8              |
| 5.1.7            | Redis                | 7.4 - 8.0          |
| 5.1.7            | Elasticsearch        | 8                  |
| 5.1.7            | Angular (Web SDK)    | 19.2               |
| 5.1.7            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

<Card title="Upgrade Path" icon="route">
  **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.8      | 5.1.7   | 5.1.6   | 5.1.5    |
| -------------------------- | ---------- | ------- | ------- | -------- |
| **process-engine**         | **9.74.4** | 9.73.1  | 9.72.7  | 9.72.5   |
| **admin**                  | **9.74.4** | 9.73.1  | 9.72.4  | 9.72.2   |
| **designer**               | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core**               | **9.45.4** | 9.44.2  | 9.43.5  | 9.43.3   |
| **scheduler-core**         | **9.34.4** | 9.33.1  | 9.32.4  | 9.32.2   |
| **events-gateway**         | **9.35.4** | 9.34.1  | 9.33.4  | 9.33.2   |
| **notification-plugin**    | **9.38.4** | 9.37.1  | 9.36.4  | 9.36.2   |
| **document-plugin**        | **9.43.4** | 9.42.2  | 9.41.5  | 9.41.3   |
| **task-management-plugin** | **9.42.4** | 9.41.1  | 9.40.4  | 9.40.2   |
| **data-search**            | **9.31.4** | 9.30.1  | 9.29.4  | 9.29.2   |
| **audit-core**             | **9.39.4** | 9.38.1  | 9.37.4  | 9.37.2   |
| **advancing-controller**   | **9.34.4** | 9.33.1  | 9.32.3  | 9.32.1   |
| **integration-designer**   | **9.58.5** | 9.57.1  | 9.56.3  | 9.56.2   |
| **application-manager**    | **9.81.4** | 9.80.2  | 9.79.6  | 9.79.3   |
| **runtime-manager**        | **9.81.4** | 9.80.2  | 9.79.6  | 9.79.3   |
| **data-sync**              | **9.32.3** | 9.31.1  | 9.30.4  | 9.30.2   |
| **authorization-system**   | **9.42.4** | 9.41.1  | 9.40.3  | 9.40.2   |
| **nosql-db-runner**        | **9.30.4** | 9.29.1  | 9.28.4  | 9.28.2   |

### Renderers

| Component                     | 5.1.8      | 5.1.7   | 5.1.6   | 5.1.5    |
| ----------------------------- | ---------- | ------- | ------- | -------- |
| **@flowx/angular-sdk**        | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme**      | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk**          | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme**        | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit**   | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk**           | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme**         | 9.164.2    | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer**              | **9.0.19** | 9.0.12  | 9.0.11  | 9.0.10   |
| **Android renderer**          | **9.0.19** | 9.0.13  | 9.0.7   | 9.0.7    |

### Plugins

| Component            | 5.1.8  | 5.1.7  | 5.1.6  | 5.1.5  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| ------------------------------- | ----- | ----- | ----- | ----- |
| **ai-assistant**                | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform**                 | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst**      | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer**     | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries**        | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                                   |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.**                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.**                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

<Warning>
  **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.
</Warning>

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

<Info>
  No configuration changes are required for this release.
</Info>

<Check>
  No required configuration changes
  No database migrations
  No breaking changes
  Compatible with existing 5.1.7 processes and configurations
</Check>

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.8            | Keycloak             | 26+                |
| 5.1.8            | Kafka                | 3.8 - 3.9          |
| 5.1.8            | PostgreSQL           | 16 - 17            |
| 5.1.8            | Oracle Database      | 21c, 23ai          |
| 5.1.8            | MongoDB              | 7 - 8              |
| 5.1.8            | Redis                | 7.4 - 8.0          |
| 5.1.8            | Elasticsearch        | 8                  |
| 5.1.8            | Angular (Web SDK)    | 19.2               |
| 5.1.8            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

<Card title="Upgrade Path" icon="route">
  **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes
</Card>

## Component versions

| Component                  | 5.1.9       | 5.1.8   | 5.1.7   | 5.1.6   |
| -------------------------- | ----------- | ------- | ------- | ------- |
| **process-engine**         | **9.75.3**  | 9.74.4  | 9.73.1  | 9.72.7  |
| **admin**                  | **9.75.3**  | 9.74.4  | 9.73.1  | 9.72.4  |
| **designer**               | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core**               | **9.46.2**  | 9.45.4  | 9.44.2  | 9.43.5  |
| **scheduler-core**         | **9.35.2**  | 9.34.4  | 9.33.1  | 9.32.4  |
| **events-gateway**         | **9.36.2**  | 9.35.4  | 9.34.1  | 9.33.4  |
| **notification-plugin**    | **9.39.2**  | 9.38.4  | 9.37.1  | 9.36.4  |
| **document-plugin**        | **9.44.2**  | 9.43.4  | 9.42.2  | 9.41.5  |
| **task-management-plugin** | **9.43.2**  | 9.42.4  | 9.41.1  | 9.40.4  |
| **data-search**            | **9.32.2**  | 9.31.4  | 9.30.1  | 9.29.4  |
| **audit-core**             | **9.40.2**  | 9.39.4  | 9.38.1  | 9.37.4  |
| **advancing-controller**   | **9.35.2**  | 9.34.4  | 9.33.1  | 9.32.3  |
| **integration-designer**   | **9.59.3**  | 9.58.5  | 9.57.1  | 9.56.3  |
| **application-manager**    | **9.82.2**  | 9.81.4  | 9.80.2  | 9.79.6  |
| **runtime-manager**        | **9.82.2**  | 9.81.4  | 9.80.2  | 9.79.6  |
| **data-sync**              | **9.33.2**  | 9.32.3  | 9.31.1  | 9.30.4  |
| **authorization-system**   | **9.43.2**  | 9.42.4  | 9.41.1  | 9.40.3  |
| **nosql-db-runner**        | **9.31.2**  | 9.30.4  | 9.29.1  | 9.28.4  |

### Renderers

| Component                     | 5.1.9       | 5.1.8   | 5.1.7   | 5.1.6   |
| ----------------------------- | ----------- | ------- | ------- | ------- |
| **@flowx/angular-sdk**        | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme**      | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk**          | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme**        | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit**   | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk**           | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme**         | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer**              | **9.0.20**  | 9.0.19  | 9.0.12  | 9.0.11  |
| **Android renderer**          | **9.0.24**  | 9.0.19  | 9.0.13  | 9.0.7   |

### Plugins

| Component            | 5.1.9  | 5.1.8  | 5.1.7  | 5.1.6  |
| -------------------- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| ------------------------------- | ----- | ----- | ----- | ----- |
| **ai-assistant**                | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform**                 | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models**          | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner**         | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst**      | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer**     | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder**   | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries**        | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component                                                           | Description                                                                                                                                                                                                   |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[SpiceDB](https://authzed.com/spicedb)**                          | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.**                     |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.hypermode.com/dgraph/overview)**            | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.**                    |

<Info>
  For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).
</Info>

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

<Info>
  No configuration changes are required for this release.
</Info>

<Check>
  No required configuration changes
  No database migrations
  No breaking changes
  Compatible with existing 5.1.8 processes and configurations
</Check>

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.9            | Keycloak             | 26+                |
| 5.1.9            | Kafka                | 3.8 - 3.9          |
| 5.1.9            | PostgreSQL           | 16 - 17            |
| 5.1.9            | Oracle Database      | 21c, 23ai          |
| 5.1.9            | MongoDB              | 7 - 8              |
| 5.1.9            | Redis                | 7.4 - 8.0          |
| 5.1.9            | Elasticsearch        | 8 - 9              |
| 5.1.9            | Angular (Web SDK)    | 19.2               |
| 5.1.9            | React (Web SDK)      | 18.x               |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-september-2025/deployment-guidelines-v5.1



<Info>
  Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Component versions

| Component                  | 5.1.0       | 5.0.0  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  | 4.7.4  | 4.7.3  | 4.7.2  | 4.7.1  | 4.7.0  | 4.6.1  | 4.6.0  | 4.1.4    | 4.1.3    | 4.1.2    | 4.1.1  | 4.1    | 4.0        | 3.4.7     | 3.4.6     | 3.4.5     | 3.4.4     | 3.4.3   | 3.4.2  | 3.4.1  | 3.4.0  | 3.3.0   | 3.2.0  | 3.1.0  | 3.0.0 |
| -------------------------- | ----------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | -------- | -------- | -------- | ------ | ------ | ---------- | --------- | --------- | --------- | --------- | ------- | ------ | ------ | ------ | ------- | ------ | ------ | ----- |
| **process-engine**         | **9.63.0**  | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0  | 8.5.1  | 8.3.1  | 8.1.1  | 8.0.2  | 6.1.4    | 6.1.3    | 6.1.2    | 6.0.3  | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5     | 4.3.2   | 4.3.1  | 4.1.0  | 3.6.0  | 2.2.1   | 2.1.2  | 2.0.7  |       |
| **admin**                  | **9.65.0**  | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2  | 7.8.13 | 7.8.5  | 7.7.6  | 7.5.1  | 7.2.6  | 7.2.3  | 5.1.6    | 5.1.5    | 5.1.4    | 5.1.3  | 5.0.9  | 4.6.10     | 3.3.19-6  | 3.3.19-4  | 3.3.19-3  | 3.3.19-1  | 3.3.19  | 3.3.10 | 3.3.7  | 3.1.1  | 2.5.2   | 2.2.2  | 2.1.3  | 2.0.8 |
| **designer**               | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1      | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core**               | **9.35.0**  | 9.21.2 | 5.10.3 | 5.9.2  | 5.8.2  | 5.5.1  | 5.4.16 | 5.4.12 | 5.4.8  | 5.3.3  | 5.2.11 | 5.2.2  | 5.1.2  | 3.0.3    | 3.0.2    | 3.0.2    | 3.0.2  | 3.0.1  | 2.2.5      | 1.3.9     | 1.3.9     | 1.3.9     | 1.3.9     | 1.3.9   | 1.3.9  | 1.3.9  | 1.3.6  | 1.3.0   | 1.2.0  | 1.0.3  | 1.0.2 |
| **scheduler-core**         | **9.25.0**  | 9.12.0 | 5.6.2  | 5.5.2  | 5.4.0  | 5.1.1  | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4  | 5.0.2  | 5.0.0  | 5.0.0  | 3.0.2    | 3.0.1    | 3.0.1    | 3.0.1  | 3.0.0  | 2.1.4      | 1.2.4     | 1.2.4     | 1.2.4     | 1.2.4     | 1.2.4   | 1.2.4  | 1.2.4  | 1.1.0  | 1.0.4   | 1.0.4  | 1.0.4  | 1.0.1 |
| **events-gateway**         | **9.25.0**  | 9.12.0 | 5.6.2  | 5.5.2  | 5.4.0  | 5.1.1  | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7  | 5.0.5  | 5.0.2  | 5.0.2  | 3.0.3    | 3.0.2    | 3.0.2    | 3.0.2  | 3.0.0  | 2.0.4      | 1.1.0     | 1.1.0     | 1.1.0     | 1.1.0     | 1.1.0   | 1.1.0  | 1.1.0  | 1.0.6  | 1.0.2   | -      | -      | -     |
| **notification-plugin**    | **9.28.0**  | 9.14.2 | 6.7.2  | 6.6.2  | 6.5.0  | 6.2.1  | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3  | 6.1.0  | 6.0.3  | 6.0.3  | 4.0.4    | 4.0.3    | 4.0.3    | 4.0.3  | 4.0.1  | 3.0.6      | 2.0.9     | 2.0.9     | 2.0.9     | 2.0.9     | 2.0.9   | 2.0.8  | 2.0.8  | 2.0.5  | 2.0.4   | 2.0.4  | 2.0.3  | 2.0.1 |
| **document-plugin**        | **9.34.0**  | 9.17.2 | 6.9.2  | 6.8.2  | 6.7.0  | 6.4.1  | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4  | 6.3.1  | 6.0.3  | 6.0.3  | 4.0.3    | 4.0.2    | 4.0.2    | 4.0.2  | 4.0.0  | 3.0.6      | 2.0.10-1  | 2.0.10    | 2.0.10    | 2.0.10    | 2.0.10  | 2.0.8  | 2.0.8  | 2.0.6  | 2.0.4   | 2.0.3  | 2.0.3  | 2.0.2 |
| **task-management-plugin** | **9.33.0**  | 9.14.2 | 7.8.2  | 7.7.2  | 7.6.0  | 7.3.1  | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6  | 7.2.2  | 7.0.3  | 7.0.3  | 5.0.5    | 5.0.4    | 5.0.4    | 5.0.4  | 5.0.2  | 4.0.5      | 3.0.3     | 3.0.3     | 3.0.3     | 3.0.3     | 3.0.3   | 3.0.3  | 3.0.3  | 3.0.0  | 2.1.2   | 1.0.4  | 1.0.4  | 1.0.1 |
| **data-search**            | **9.22.0**  | 9.12.1 | 4.6.2  | 4.5.2  | 4.4.0  | 4.1.1  | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6  | 4.0.4  | 4.0.0  | 4.0.0  | 2.0.5    | 2.0.4    | 2.0.4    | 2.0.4  | 2.0.3  | 1.0.6      | 0.2.8     | 0.2.8     | 0.2.8     | 0.2.6     | 0.2.6   | 0.2.6  | 0.2.6  | 0.2.3  | 0.2.0   | 0.1.4  | 0.1.4  | 0.1.3 |
| **audit-core**             | **9.29.1**  | 9.15.2 | 6.7.2  | 6.6.2  | 6.5.0  | 6.1.1  | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6  | 6.0.4  | 6.0.0  | 6.0.0  | 4.0.5    | 4.0.4    | 4.0.4    | 4.0.4  | 4.0.3  | 3.1.4      | 2.2.0     | 2.2.0     | 2.2.0     | 2.2.0     | 2.2.0   | 2.1.3  | 2.1.3  | 2.1.0  | 1.0.6   | 1.0.5  | 1.0.4  | 1.0.1 |
| **advancing-controller**   | **9.24.0**  | 9.11.0 | 4.6.2  | 4.6.2  | 4.4.0  | 4.1.1  | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5  | 4.0.3  | 4.0.0  | 4.0.0  | 2.0.3    | 2.0.2    | 2.0.2    | 2.0.2  | 2.0.0  | 1.1.4      | 0.3.5-1   | 0.3.5     | 0.3.5     | 0.3.5     | 0.3.5   | 0.3.5  | 0.3.5  | 0.3.2  | 0.3.0   | 0.1.4  | 0.1.4  | 0.1.2 |
| **integration-designer**   | **9.49.1**  | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0  | 2.7.2  | 2.6.0  | 2.3.16 | 2.3.9  | 2.3.2  | 2.0.4  | 2.0.1  |          |          |          |        |        |            |           |           |           |           |         |        |        |        |         |        |        |       |
| **application-manager**    | **9.72.0**  | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4  | 2.6.0  | 2.0.25 | 2.0.18 | -        | -        | -        | -      | -      | -          | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **runtime-manager**        | **9.72.0**  | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4  | 2.6.0  | 2.0.25 | 2.0.18 | -        | -        | -        | -      | -      | -          | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **data-sync**              | **9.21.0**  | 9.11.0 | 2.9.2  | 2.8.1  | 2.7.1  | 2.4.1  | 2.3.2  | 2.2.11 | 2.2.9  | 2.2.2  | 2.1.0  | 2.0.2  | 2.0.2  | -        | -        | -        | -      | -      | -          | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **authorization-system**   | **9.33.0**  | 9.14.2 | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -        | -        | -        | -      | -      | -          | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **nosql-db-runner**        | **9.21.0**  | 9.11.0 | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -        | -        | -        | -      | -      | -          | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component                     | 5.1.0       | 5.0.0  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  | 4.7.4  | 4.7.3  | 4.7.2  | 4.7.1  | 4.7.0  | 4.6.1  | 4.6.0  | 4.1.4    | 4.1.3    | 4.1.2    | 4.1.1  | 4.1    | 4.0       | 3.4.7     | 3.4.6     | 3.4.5     | 3.4.4     | 3.4.3   | 3.4.2  | 3.4.1  | 3.4.0  | 3.3.0   | 3.2.0  | 3.1.0  | 3.0.0 |
| ----------------------------- | ----------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | -------- | -------- | -------- | ------ | ------ | --------- | --------- | --------- | --------- | --------- | ------- | ------ | ------ | ------ | ------- | ------ | ------ | ----- |
| **@flowx/angular-sdk**        | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        |          |        |        |           |           |           |           |           |         |        |        |        |         |        |        |       |
| **@flowx/angular-theme**      | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        |          |        |        |           |           |           |           |           |         |        |        |        |         |        |        |       |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1     | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk**          | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        | -        | -      | -      | -         | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **@flowx/react-theme**        | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        | -        | -      | -      | -         | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **@flowx/react-ui-toolkit**   | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        | -        | -      | -      | -         | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **@flowx/core-sdk**           | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        | -        | -      | -      | -         | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **@flowx/core-theme**         | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | -        | -        | -        | -      | -      | -         | -         | -         | -         | -         | -       | -      | -      | -      | -       | -      | -      |       |
| **paperflow-web-components**  | -           | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -      | -        | -        | -        | -      | -      | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer**              | **9.0.4**   | 9.0.0  | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7  | 4.0.7  | 4.0.5  | 4.0.4  | 4.0.3  | 3.0.20   | 3.0.20   | 3.0.20   | 3.0.20 | 3.0.20 | 3.0.0     | 2.3.0     | 2.3.0     | 2.3.0     | 2.3.0     | 2.3.0   | 2.3.0  | 2.3.0  | 2.3.0  | 2.1.0   | 2.0.1  | 2.0.0  | 2.0.0 |
| **Android renderer**          | **9.0.2**   | 9.0.0  | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9  | 3.0.23   | 3.0.23   | 3.0.23   | 3.0.23 | 3.0.23 | 3.0.0     | 2.1.4     | 2.1.4     | 2.1.4     | 2.1.4     | 2.1.4   | 2.1.4  | 2.1.4  | 2.1.4  | 2.0.1   | 2.0.1  | 2.0.1  | 2.0.1 |

### Plugins

| Component            | 5.1.0     | 5.0.0  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  | 4.7.4  | 4.7.3  | 4.7.2  | 4.7.1  | 4.7.0  | 4.6.1  | 4.6.0  | 4.1.4  | 4.1.3  | 4.1.2  | 4.1.1  | 4.1    | 4.0    | 3.4.7  | 3.4.6  | 3.4.5  | 3.4.4  | 3.4.3  | 3.4.2  | 3.4.1  | 3.4.0 | 3.3.0  | 3.2.0  | 3.1.0  | 3.0.0  |
| -------------------- | --------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ----- | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17    | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8  | 1.0.2  | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.3** | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6  | 0.1.6  | 0.1.6  | 0.1.6  | 0.1.6  | 0.1.5  | 0.1.2  | 0.1.2  | 0.1.2  | 0.1.2  | 0.1.2  | 0.1.2  | 0.1.2  | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component           | 5.1.0     | 5.0.0  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  | 4.7.4  | 4.7.3  | 4.7.2 | 4.7.1  | 4.7.0  | 4.6.1  | 4.6.0  | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| ------------------- | --------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ----- | ------ | ------ | ------ | ------ | ----- | ----- | ----- | ----- | --- | --- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
| **ai-assistant**    | **9.2.4** | 9.2.3  | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2  | 1.7.2  | 1.6.15 | 1.6.9  | -     | -     | -     | -     | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |       |
| **di-platform**     | **9.3.1** | 9.0.12 | 1.4.6  | 1.4.6  | 1.4.5  | 1.4.5  | 1.4.5  | 1.4.3  | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | -     | -     | -     | -     | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |       |
| **ai-developer**    | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **connected-graph** | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **knowledge-graph** | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **agents**          | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **conversations**   | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **models**          | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **tenants**         | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **planner**         | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **ai-designer**     | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |
| **ai-analyst**      | **9.3.0** | 9.0.1  | -      | -      | -      | -      | -      | -      | -     | -      | -      | -      | -      | -     | -     | -     |       | -   | -   | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     | -     |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.1.0            | Keycloak             | 26+                |
| 5.1.0            | Kafka                | 3.8 - 3.9          |
| 5.1.0            | PostgreSQL           | 16 - 17            |
| 5.1.0            | Oracle Database      | 21c, 23ai          |
| 5.1.0            | MongoDB              | 7 - 8              |
| 5.1.0            | Redis                | 7.4 - 8.0          |
| 5.1.0            | Elasticsearch        | 8 - 9              |
| 5.1.0            | Angular (Web SDK)    | 19.x               |
| 5.1.0            | React (Web SDK)      | 18.x               |

<Warning>
  Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:

  * Keycloak versions older than 26
  * Kafka versions older than 3.8
  * Redis versions older than 7.4
</Warning>


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-september-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

<Note>
  Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.
</Note>

### Variables to remove & replace

| Remove This Variable                            | Replace With                                 | Old Default  | New Default  |
| ----------------------------------------------- | -------------------------------------------- | ------------ | ------------ |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME`     | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS`     | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS`   | `2`          | `2`          |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`   | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2`          | `0`          |

### New variables to add

| Variable                                | Default Value | Description                     |
| --------------------------------------- | ------------- | ------------------------------- |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30`          | Automatic index rollover policy |

## Data Search

<Note>
  Simple migration with containerization support and namespace alignment.
</Note>

### Variables to update

| Variable                         | Current Value    | New Value            | Reason                   |
| -------------------------------- | ---------------- | -------------------- | ------------------------ |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This                               | Add This                                 | Default Value      |
| ----------------------------------------- | ---------------------------------------- | ------------------ |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

<Note>
  New configuration option for test documents bucket customization.
</Note>

### New variables to add

| Variable                                     | Default Value     | Description                                                                                                    |
| -------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

<Info>
  This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.
</Info>

## Kafka configuration

<Info>
  Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.
</Info>

<Warning>
  **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.
</Warning>

### Consumer group migrations

<Accordion title="View all 33 consumer group name changes across all FlowX.AI services">
  **Admin (3 groups):**

  | Old Group ID                       | New Group ID                           |
  | ---------------------------------- | -------------------------------------- |
  | `genericProcessingGroup`           | `generic-processing-group`             |
  | `processSyncGroup`                 | `process-sync-group`                   |
  | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |

  **Application Manager (15 groups):**

  | Old Group ID                        | New Group ID                              |
  | ----------------------------------- | ----------------------------------------- |
  | `appResourceExportGroup`            | `app-resource-export-group`               |
  | `appResourceImportGroup`            | `app-resource-import-group`               |
  | `appResourceUsagesGroup`            | `app-resource-usages-group`               |
  | `appResElemUsageValidationResp`     | `app-resource-elem-usage-validation-resp` |
  | `appResourceCopyGroup`              | `app-resource-copy-group`                 |
  | `appResourceSyncGroup`              | `app-resource-sync-group`                 |
  | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group`   |
  | `appMergeItemGroup`                 | `app-merge-item-group`                    |
  | `buildCreateGroup`                  | `build-create-group`                      |
  | `buildUpdateGroup`                  | `build-update-group`                      |
  | `buildResourceExportGroup`          | `build-resource-export-group`             |
  | `buildResourceImportGroup`          | `build-resource-import-group`             |
  | `buildRuntimeDataGroup`             | `build-runtime-data-group`                |
  | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group`  |
  | `processStartGroup`                 | `process-start-group`                     |

  **CMS Core (1 group):**

  | Old Group ID           | New Group ID         |
  | ---------------------- | -------------------- |
  | `cms-consumer-preview` | `cms-consumer-group` |

  **Document Plugin (1 group):**

  | Old Group ID                              | New Group ID                  |
  | ----------------------------------------- | ----------------------------- |
  | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |

  **Integration Designer (3 groups):**

  | Old Group ID                                | New Group ID                                           |
  | ------------------------------------------- | ------------------------------------------------------ |
  | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group`  |
  | `genericProcessingGroup`                    | `start-workflows-group`                                |
  | `resElemUsageValidation`                    | `integration-designer-res-elem-usage-validation-group` |

  **Notification Plugin (1 group):**

  | Old Group ID       | New Group ID                   |
  | ------------------ | ------------------------------ |
  | `notif123-preview` | `notification-plugin-consumer` |

  **Process Engine (11 groups):**

  | Old Group ID (all were `notif123-preview`) | New Group ID               |
  | ------------------------------------------ | -------------------------- |
  | `notif123-preview`                         | `advance`                  |
  | `notif123-preview`                         | `notify-parent`            |
  | `notif123-preview`                         | `adapters`                 |
  | `notif123-preview`                         | `scheduler-run-action`     |
  | `notif123-preview`                         | `scheduler-advancing`      |
  | `notif123-preview`                         | `message-events`           |
  | `notif123-preview`                         | `process-start`            |
  | `notif123-preview`                         | `process-start-for-event`  |
  | `notif123-preview`                         | `process-expire`           |
  | `notif123-preview`                         | `process-operations`       |
  | `notif123-preview`                         | `process-batch-processing` |
</Accordion>

### Kafka topic migrations

<Note>
  All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.
</Note>

<Tabs>
  <Tab title="Application Manager">
    **Application resource topics:**

    | Environment Variable                                                                | New Topic Name                                                                             |
    | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN`                   | `ai.flowx.application-version.correction-after-app-operation.response.v1`                  |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS`          | `ai.flowx.application-version.correction-after-app-operation.process.request.v1`           |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE`     | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1`     |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |

    **Sync topics:**

    | Environment Variable                                            | New Topic Name                                              |
    | --------------------------------------------------------------- | ----------------------------------------------------------- |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN`          | `ai.flowx.application-version.sync.process.in.v1`           |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN`     | `ai.flowx.application-version.sync.business-rule.in.v1`     |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN`                      | `ai.flowx.application-version.sync.out.v1`                  |

    **Resource update propagation:**

    | Environment Variable                                 | New Topic Name                                                |
    | ---------------------------------------------------- | ------------------------------------------------------------- |
    | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |

    **Build resource topics:**

    | Environment Variable            | New Topic Name                   |
    | ------------------------------- | -------------------------------- |
    | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |
  </Tab>

  <Tab title="Admin">
    **Consumer groups:**

    | Environment Variable                                         | New Consumer Group                        | Threads |
    | ------------------------------------------------------------ | ----------------------------------------- | ------- |
    | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC`                        | `process-sync-group`                      | `6`     |
    | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC`                  | `business-rule-sync-group`                | `6`     |
    | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC`              | `reusable-template-sync-group`            | `6`     |
    | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6`     |

    **Application sync topics:**

    | Environment Variable                            | New Topic Name                                              |
    | ----------------------------------------------- | ----------------------------------------------------------- |
    | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE`         | `ai.flowx.application-version.sync.out.v1`                  |
    | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC`          | `ai.flowx.application-version.sync.process.in.v1`           |
    | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC`     | `ai.flowx.application-version.sync.business-rule.in.v1`     |
    | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |

    **Application correction after app operation topics:**

    | Environment Variable                                                      | New Topic Name                                                                             |
    | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
    | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS`          | `ai.flowx.application-version.correction-after-app-operation.process.request.v1`           |
    | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE`     | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1`     |
    | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
    | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT`                 | `ai.flowx.application-version.correction-after-app-operation.response.v1`                  |

    **Build topics:**

    | Environment Variable            | New Topic Name                   |
    | ------------------------------- | -------------------------------- |
    | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |
  </Tab>
</Tabs>

### New Kafka features

<CardGroup>
  <Card title="Resource Update Propagation" icon="arrow-right-arrow-left">
    **Consumer Group:** `app-resource-update-propagation-group`\
    **Threads:** 3\
    **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
    **Purpose:** Real-time resource change propagation
  </Card>

  <Card title="Build Runtime Data" icon="database">
    **Consumer Group:** `build-runtime-data-group`\
    **Threads:** 2\
    **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
    **Purpose:** Build process data management
  </Card>

  <Card title="Business Rule Sync" icon="code-branch">
    **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
    **Purpose:** Enhanced business rule synchronization\
    **Consumer Group:** `business-rule-sync-group`
  </Card>

  <Card title="Process Sync Enhanced" icon="workflow">
    **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
    **Purpose:** Improved process synchronization\
    **Consumer Group:** `process-sync-group`
  </Card>

  <Card title="Reusable Template Sync" icon="puzzle-piece">
    **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
    **Purpose:** Template synchronization\
    **Consumer Group:** `reusable-template-sync-group`
  </Card>

  <Card title="Correction After App Operation" icon="refresh">
    **Multiple Topics:** Process, business rule, and template correction\
    **Purpose:** Post-deployment resource correction\
    **Consumer Group:** `processCorrectionAfterAppOperationGroup`
  </Card>
</CardGroup>

### Configure environment variables

<Info>
  **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.
</Info>

<CodeGroup>
  ```bash Application Manager Topics theme={"system"}
  # Resource Update Propagation
  KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

  # Build Runtime Data  
  KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

  # Sync Topics
  KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
  KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
  KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

  # Correction After App Operation
  KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
  KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
  KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
  ```

  ```bash Admin Topics theme={"system"}
  # Application Sync
  KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
  KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
  KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
  KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

  # Correction After App Operation
  KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
  KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
  KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
  KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
  ```

  ```bash Consumer Groups and Threads theme={"system"}
  # Application Manager Consumer Groups
  KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
  KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

  # Admin Consumer Groups  
  KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
  KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
  KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
  KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

  # Thread Configuration
  KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
  KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
  KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
  KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
  KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
  KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
  ```
</CodeGroup>

### Additional Application Manager variables

| Variable                                                         | Default Value | Description                      |
| ---------------------------------------------------------------- | ------------- | -------------------------------- |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300`         | Refresh expiration timeout       |
| `SERVER_MAXHTTPREQUESTHEADERSIZE`                                | `16KB`        | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable                                       | Default Value       | Description           |
| ---------------------------------------------- | ------------------- | --------------------- |
| `APPLICATION_FILESTORAGE_TYPE`                 | `s3`                | Storage type          |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY`    | `NONE`              | Partition strategy    |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY`     | `delete`            | Deletion strategy     |
| `APPLICATION_FILESTORAGE_S3_ENABLED`           | `true`              | S3 enabled            |
| `APPLICATION_FILESTORAGE_S3_SERVERURL`         | `http://minio:9000` | S3 server URL         |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false`             | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY`         | `minio`             | S3 access key         |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY`         | `minio123`          | S3 secret key         |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`      | `workflows-bucket`  | S3 bucket prefix      |

### Redis

Added caching when running a workflow.

| Variable                        | Default Value                            | Description        |
| ------------------------------- | ---------------------------------------- | ------------------ |
| `SPRING_CACHE_TYPE`             | `redis`                                  | Cache type         |
| `SPRING_CACHE_REDIS_KEYPREFIX`  | `flowx:core:cache:integration-designer:` | Cache key prefix   |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000`                                | Cache time to live |
| `SPRING_REDIS_HOST`             | `redis-master`                           | Redis host         |
| `SPRING_REDIS_PORT`             | `6379`                                   | Redis port         |
| `SPRING_REDIS_PASSWORD`         | `defaultpassword`                        | Redis password     |
| `SPRING_REDIS_TTL`              | `5000000`                                | Redis time to live |
| `SPRING_DATA_REDIS_HOST`        | `spring.redis.host`                      | Redis host         |

## FlowX Engine

<Note>
  The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.
</Note>

### Variables to remove & replace

| Remove This Variable         | Replace With                                     |
| ---------------------------- | ------------------------------------------------ |
| `ADVANCING_THREADS`          | `ADVANCING_PICKINGTHREADS` (default: `1`)        |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable                                    | Default Value | Description                                                    |
| ------------------------------------------- | ------------- | -------------------------------------------------------------- |
| `ADVANCING_PROCESSINGTHREADS`               | `20`          | Number of threads for parallel processing of advancing events  |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true`        | Block picking operations when no worker threads are available  |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE`      | `20`          | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable                       | Current Value | New Value | Reason                                          |
| ------------------------------ | ------------- | --------- | ----------------------------------------------- |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100`         | `50`      | Optimized pause duration for better performance |

<Info>
  **How the new advancing controller works:**

  * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.

  * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.

  * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.

  * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.
</Info>

### Elasticsearch indexing configuration

<Note>
  Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.
</Note>

#### Variables to remove & replace

| Remove This Variable                           | Replace With                                 | Old Default        | New Default        |
| ---------------------------------------------- | -------------------------------------------- | ------------------ | ------------------ |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE`                        | `kafka`            | `kafka`            |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME`    | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME`     | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS`        | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS`   | `2`                | `2`                |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS`      | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2`                | `0`                |

<Info>
  For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.
</Info>

## Java runtime configuration

<Note>
  FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.
</Note>

| Deprecated variables             | Standard Replacement | Notes                                                              |
| -------------------------------- | -------------------- | ------------------------------------------------------------------ |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS`   | Ensures compatibility with Java 21 and simplifies container config |

<Info>
  Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.
</Info>

## Config profiles

<Info>
  Config profiles are deprecated since 4.7.6 version.
</Info>

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

<Note>
  For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.
</Note>

| Remove This Variable | Replace With            | Environment |
| -------------------- | ----------------------- | ----------- |
| `CONFIG_PROFILE`     | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

<Info>
  FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.
</Info>

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable              | Default Value | Description                                                                                           |
| --------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `FLOWX_SPICEDB_HOST`  | `spicedb`     | SpiceDB server hostname. Change only if your deployment uses a non-default host.                      |
| `FLOWX_SPICEDB_PORT`  | `50051`       | SpiceDB server port. Change only if your deployment uses a non-default port.                          |
| `FLOWX_SPICEDB_TOKEN` | *(secret)*    | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable                               | Default Value | Description                                                                                           |
| -------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `FLOWX_SPICEDB_HOST`                   | `spicedb`     | SpiceDB server hostname. Change only if your deployment uses a non-default host.                      |
| `FLOWX_SPICEDB_PORT`                   | `50051`       | SpiceDB server port. Change only if your deployment uses a non-default port.                          |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL`      | -             | Authentication system URL.                                                                            |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | -             | Authentication system username.                                                                       |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | -             | Authentication system password.                                                                       |
| `FLOWX_SPICEDB_TOKEN`                  | -             | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable                         | Old Default | New Default | Description                        |
| -------------------------------- | ----------- | ----------- | ---------------------------------- |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies)    | `""`        | Moved to default empty environment |

<Info>
  This change standardizes topic naming across environments by defaulting to an empty environment identifier.
</Info>

## CORS and ingress updates

<Warning>
  All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.
</Warning>

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"system"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service              | Fx-Workspace-Id Required | Reference                                                                                       |
| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| Admin                | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |
| Application Manager  | ✅ Yes                    | [Ingress guide](../../../../..5.1/setup-guides/ingress-configuration)                           |
| Audit Core           | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |
| Authorization System | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |
| Events Gateway       | ❌ No (SSE)               | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |
| Process Engine       | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |
| Runtime Manager      | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |
| Task Management      | ✅ Yes                    | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration)                          |

<Card title="Complete Ingress Configuration Guide" href="../../../../../5.1/setup-guides/ingress-configuration" icon="network-wired">
  View the complete ingress configuration pattern including:

  * Standard template for all services
  * Service-specific paths and rewrite rules
  * Annotation explanations
  * Troubleshooting guide
  * Environment-specific customization
</Card>

<Info>
  **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.
</Info>


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-september-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

<Card title="authorization-system" href="../../../../../5.1/setup-guides/authorization-setup-guide" icon="scroll" />

<Card title="nosql-db-runner" href="../../../../../5.1/setup-guides/nosql-db-runner" icon="scroll" />


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-september-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

<Warning>
  You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.
</Warning>

## Success factors

<Warning>
  Take care when following the steps below are mandatory and will prevent service startup if skipped:

  1. **SpiceDB and DGraph** must be installed before any FlowX.AI services

  <Info>
    DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
  </Info>

  2. **Organization admin user** must be configured before authorization-system service deployment
  3. **Service accounts** must have `SA_FLOWX` role assigned
  4. **Elasticsearch indices (data migration)** must complete before service upgrades
</Warning>

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

<Steps>
  <Step title="Prerequisites">
    ### Data migration (Elasticsearch indices)

    Migrate existing Elasticsearch data to support the new workspace-based architecture.

    ### Installing new third parties

    **New mandatory infrastructure components:**

    * **SpiceDB** - Authorization and permission management backend
    * **DGraph** - Graph-based data operations and relationships

    ### Upgrading existing third parties

    Update existing infrastructure to the new supported versions:

    * Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

    ### Organization admin user

    Configure the organization admin user before deploying the authorization-system service.

    ### Service accounts

    Assign `SA_FLOWX` role to all service accounts used by FlowX services.

    <Card title="Prerequisites" href="./prerequisites" icon="scroll">
      See the details on prerequisites for migration
    </Card>
  </Step>

  <Step title="Installing new services">
    Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

    **Required installation sequence:**

    1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
    2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

    <Warning>
      **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.
    </Warning>

    <Card title="Install services" href="./install-services" icon="server">
      Step-by-step installation with validation procedures
    </Card>

    <Info>
      Installing Authorization System first allows you to validate all critical configurations before proceeding.
    </Info>
  </Step>

  <Step title="Update environment variables">
    Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

    **Configuration updates include:**

    * New Kafka topics and consumer groups
    * Updated Elasticsearch settings and index configurations
    * Enhanced security and authorization parameters
    * New service integration endpoints

    <Card title="Update environment variables" href="./environment-variables" icon="engine">
      Update environment variables for all existing FlowX.AI services
    </Card>
  </Step>

  <Step title="Install new versions for existing services">
    Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.
  </Step>

  <Step title="Container apps (Renderers SDKs)">
    <Card title="Container apps (Renderers SDKs)" href="./renderers" icon="scroll">
      See the details on container apps (Renderers SDKs)
    </Card>
  </Step>

  <Step title="Post-deployment steps">
    Perform the post deployment steps:

    * Validate data-sync migrations
    * Clear cache with endpoint
    * Remove deprecated configuration roles (optional)
    * Add users to default workspace

    ### Validate data-sync migrations

    Verify that all data synchronization processes completed successfully and perform additional system checks.

    ### Clear cache with endpoint

    **Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

    <Warning>
      **Cache Clearing**:

      * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
      * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.
    </Warning>

    ### Remove deprecated configuration roles (optional)

    Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

    ### Add users to default workspace

    **Process**:

    1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
    2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

    <Warning>
      **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.
    </Warning>

    <Card title="Post-deployment configuration" href="./configuration-and-migration" icon="scroll">
      Complete post-deployment procedures and validation
    </Card>

    <Card title="Troubleshooting" href="./troubleshooting" icon="wrench">
      Common issues and solutions for post-upgrade problems
    </Card>
  </Step>
</Steps>


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-september-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component         | 4.7.8     | FlowX.AI 5.1.0 |
| ----------------- | --------- | -------------- |
| **Kafka**         | 3.2 - 3.9 | **3.8 - 3.9**  |
| **Redis**         | 7.2 - 8.0 | **7.4 - 8.0**  |
| **Elasticsearch** | 7 - 9     | **8 - 9**      |
| **Keycloak**      | 22,26+    | **26+**        |

<Card title="Third parties components versions" href="../deployment-guidelines-v5.1#third-party-recommended-component-versions" icon="scroll" />

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

<Card title="SpiceDB setup guide" href="../../../../../5.1/setup-guides/spicedb" icon="scroll" />

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

<Warning>
  Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.
</Warning>

### Migration timing

<Tip>
  **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.
</Tip>

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"system"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"system"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"system"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"system"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"system"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

<CardGroup>
  <Card title="Authorization system" href="../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap" icon="scroll" />

  <Card title="Workspaces access rights" href="../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin-org-admin" icon="scroll" />
</CardGroup>

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

<Tabs>
  <Tab title="Recommended: Use admin email (simpler)">
    Set the following authorization-system environment variables:

    * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
    * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.
  </Tab>

  <Tab title="Alternative: Use admin subject ID">
    Set the following environment variables:

    * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
    * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).

    <Tip>
      To get the subject ID of the admin user, extract it from the JWT token of the admin user.
    </Tip>

    <Frame>
      ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)
    </Frame>
  </Tab>
</Tabs>

<Info>
  Make sure the admin user is created in Keycloak before deploying the authorization-system service.
</Info>

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

<Warning>
  All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.
</Warning>

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"system"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

<Warning>
  For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.
</Warning>


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-september-2025/v5.1.0-september-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

<Tabs>
  <Tab title="Reusability">
    Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.

    🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
    🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
    🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
    🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
    🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
    🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
    🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts

    ### **Project Data Model (PDM)**

    <Card title="Project Data Model (PDM)" icon="database">
      <Tabs>
        <Tab title="PDM Overview">
          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
          </Frame>

          The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
        </Tab>

        <Tab title="PDM Key Features">
          <CardGroup>
            <Card title="Centralized Management" icon="sitemap">
              Define data types once at the project level and reuse them across multiple processes
            </Card>

            <Card title="Automatic Propagation" icon="arrows-rotate">
              Changes to PDM data types automatically propagate to all referencing processes
            </Card>

            <Card title="Enhanced Governance" icon="shield-check">
              Configure sensitive data and reporting settings at the project level
            </Card>

            <Card title="Library Integration" icon="books">
              Use data types from libraries in your Project Data Model
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="PDM Benefits">
          <Steps>
            <Step title="Reduce duplicate work">
              Define common data types like Customer, Product, or Document once instead of recreating them in each process
            </Step>

            <Step title="Simplify maintenance">
              Update a data type in one place and have changes apply everywhere it's used
            </Step>

            <Step title="Standardize data structures">
              Enforce consistent naming, structure, and governance across your application
            </Step>

            <Step title="Accelerate development">
              Create new processes faster by leveraging pre-defined data types
            </Step>
          </Steps>
        </Tab>

        <Tab title="Example">
          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
          </Frame>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/building-blocks/process/project-data-model">
          Learn more about Project Data Model

          <svg>
            <path />
          </svg>
        </a>

        <span>
          New Feature
        </span>
      </div>
    </Card>

    ***

    ### **Library-to-Library Dependencies**

    <Card title="Library-to-Library Dependencies" icon="list">
      <Tabs>
        <Tab title="Lib2Lib Dependencies Overview">
          <Frame>
            ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
          </Frame>

          FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
        </Tab>

        <Tab title="Lib2Lib Dependencies Key Features">
          <CardGroup>
            <Card title="Hierarchical Structure" icon="sitemap">
              Create complex dependency trees with multiple levels of library-to-library relationships
            </Card>

            <Card title="Resource Inheritance" icon="arrow-down">
              Projects automatically gain access to resources from the entire dependency hierarchy
            </Card>

            <Card title="Version Control" icon="tag">
              Single-version constraint ensures consistency across the dependency tree
            </Card>

            <Card title="Conflict Prevention" icon="shield-exclamation">
              Built-in validation prevents circular dependencies and version conflicts
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Lib2Lib Dependencies Benefits">
          <Steps>
            <Step title="Enhanced Modularity">
              Break down complex functionality into smaller, focused libraries that can depend on each other
            </Step>

            <Step title="Team-based Development">
              Enable different teams to own and maintain specific libraries while building on shared foundations
            </Step>

            <Step title="Specialized Libraries">
              Create country-specific or domain-specific libraries that extend common base libraries
            </Step>

            <Step title="Simplified Architecture">
              Organize libraries hierarchically, reducing complexity and improving maintainability
            </Step>
          </Steps>
        </Tab>

        <Tab title="Example Structure">
          <Frame>
            ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
          </Frame>

          <Accordion title="Sample dependency hierarchy">
            ```
            Mortgage Project
            ├── Enums Library (1.6.0)
            ├── Integrations Library (2.5.0)
            │   ├── Commons Library (1.1.0)  
            │   └── Enums Library (1.6.0) # Transitive dependency
            └── Subprocesses Library (1.3.0)
                └── Enums Library (1.6.0)  # Transitive dependency
            ```

            In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/projects/managing-applications/dependencies">
          Learn more about Library Dependencies

          <svg>
            <path />
          </svg>
        </a>

        <span>
          Major Enhancement
        </span>
      </div>
    </Card>

    ### **Data Mappers**

    <Card title="Data Mappers" icon="arrow-right-arrow-left">
      <Tabs>
        <Tab title="Data Mappers Overview">
          <video />

          Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
        </Tab>

        <Tab title="Data Mappers Key Features">
          <CardGroup>
            <Card title="Visual Data Mapping" icon="diagram-project">
              Drag-and-drop interface for mapping data between source and destination components
            </Card>

            <Card title="Component Integration" icon="puzzle-piece">
              Seamlessly connect processes, subprocesses, workflows, and business rules
            </Card>

            <Card title="Parameter Management" icon="sliders">
              Define input/output parameters with predefined and flexible parameter types
            </Card>

            <Card title="Backward Compatibility" icon="shield-check">
              Choose between new Data Mapper or existing implementation methods
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Data Mappers Benefits">
          <Steps>
            <Step title="Simplified Integration">
              Visual interface eliminates complex configuration syntax and reduces integration errors
            </Step>

            <Step title="Enhanced Reusability">
              Define parameters once and reuse across multiple components and processes
            </Step>

            <Step title="Improved Governance">
              Centralized parameter management with clear data flow visibility
            </Step>

            <Step title="Zero Migration Risk">
              Optional adoption with full backward compatibility ensures smooth transition
            </Step>
          </Steps>
        </Tab>

        <Tab title="Data Mappers Use Cases">
          <CardGroup>
            <Card title="Call Activity Mapping" icon="arrow-right">
              Map data between parent processes and subprocesses (sync/async)
            </Card>

            <Card title="Integration Workflows" icon="workflow">
              Connect processes with Integration Designer workflows
            </Card>

            <Card title="Business Rules" icon="scale-balanced">
              Pass data to and from business rule executions
            </Card>

            <Card title="Node-to-Node Data Flow" icon="share-nodes">
              Map data between workflow nodes (REST endpoints, data persistence)
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/building-blocks/process/data-mappers">
          Learn more about Data Mappers

          <svg>
            <path />
          </svg>
        </a>

        <span>
          New Feature
        </span>
      </div>
    </Card>

    ***

    ### **Reusable Resources**

    <Card title="Reusable Resources" icon="puzzle-piece">
      <Tabs>
        <Tab title="Reusable Resources Overview">
          <Frame>
            ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
          </Frame>

          FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
        </Tab>

        <Tab title="Reusable Functions">
          <CardGroup>
            <Card title="Business Logic Reuse" icon="code">
              Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
            </Card>

            <Card title="Data Model Integration" icon="database">
              Define input/output parameters with full project data model integration and testing capabilities
            </Card>

            <Card title="Interactive Testing" icon="flask">
              Test functions with sample data in real-time before deployment to ensure accuracy
            </Card>

            <Card title="Automatic Propagation" icon="arrows-rotate">
              Changes to functions automatically update all instances across your application
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Reusable UI Templates">
          <CardGroup>
            <Card title="UI Component Reuse" icon="window">
              Design UI components once and instantiate them across multiple User Tasks with automatic data binding
            </Card>

            <Card title="Centralized Management" icon="sitemap">
              Manage all templates from the new Reusable Resources section alongside Reusable Functions
            </Card>

            <Card title="Omnichannel Support" icon="devices">
              Templates work seamlessly across different platforms and channels
            </Card>

            <Card title="Flexible UI Actions" icon="mouse-pointer">
              Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Key Problems Solved">
          <Steps>
            <Step title="Eliminate repetitive development">
              Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
            </Step>

            <Step title="End manual component updates">
              Update functions and templates in one place to automatically affect all instances across your application
            </Step>

            <Step title="Centralized template management">
              Replace scattered, inconsistent UI patterns with centrally managed, reusable components
            </Step>

            <Step title="Accelerate time-to-market">
              Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
            </Step>
          </Steps>
        </Tab>

        <Tab title="Real-World Examples">
          <Accordion title="Reusable Functions Examples">
            **Customer Data Validation Function:**

            * **Input**: firstName, lastName, email, phone
            * **Logic**: Format validation, duplicate checking, data standardization
            * **Output**: validatedCustomer object with formatted data
            * **Usage**: Customer onboarding, profile updates, registration processes across all channels

            **Credit Risk Assessment Function:**

            * **Input**: applicationData, customerProfile, financialHistory
            * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
            * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
            * **Usage**: Loan applications, credit cards, mortgage processes, business lending

            **Document Processing Function:**

            * **Input**: documentFile, documentType, customerID
            * **Logic**: OCR processing, data extraction, compliance validation
            * **Output**: extractedData, validationStatus, complianceFlags
            * **Usage**: KYC processes, claims processing, application reviews
          </Accordion>

          <Accordion title="Reusable UI Templates Examples">
            **Personal Details Card Template:**

            * **Root Component**: Card with professional styling
            * **Contains**: Name, email, phone, address input fields with validation
            * **UI Actions**: Save data, clear form, auto-populate from existing data
            * **Usage**: Customer registration, profile updates, employee onboarding, contractor management

            **Document Upload Section Template:**

            * **Root Component**: Container with drag-and-drop functionality
            * **Contains**: File upload area, progress indicators, document list, preview capabilities
            * **UI Actions**: Upload documents, delete files, download copies, validate formats
            * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes

            **Financial Summary Dashboard Template:**

            * **Root Component**: Card with data visualization
            * **Contains**: Balance displays, transaction history, chart components, action buttons
            * **UI Actions**: Refresh data, export reports, drill-down details
            * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <div>
          <a href="../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions">
            Learn about Reusable Functions

            <svg>
              <path />
            </svg>
          </a>

          <a href="../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui">
            Learn about UI Templates

            <svg>
              <path />
            </svg>
          </a>
        </div>

        <span>
          Major Feature
        </span>
      </div>
    </Card>

    ***

    ### **Files in Integration Designer**

    <Card title="Files in Integration Designer" icon="file-code">
      <Tabs>
        <Tab title="Files Overview">
          <Frame>
            ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
          </Frame>

          FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
        </Tab>

        <Tab title="Core File Scenarios">
          <CardGroup>
            <Card title="File Downloads" icon="download">
              Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
            </Card>

            <Card title="File Uploads" icon="upload">
              Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
            </Card>

            <Card title="Document Plugin Integration" icon="folder">
              Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
            </Card>

            <Card title="S3 Storage Support" icon="cloud">
              Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Enhanced Capabilities">
          <Steps>
            <Step title="Automated File Exchange">
              Enable seamless file transfer with external systems without manual handling or complex custom integrations
            </Step>

            <Step title="Flexible Storage Options">
              Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
            </Step>

            <Step title="Workflow Integration">
              Files are automatically integrated into workflow processes with proper path management and metadata handling
            </Step>

            <Step title="External Service Communication">
              Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
            </Step>
          </Steps>
        </Tab>

        <Tab title="Real-World Use Cases">
          <Accordion title="Contract Generation Workflows">
            **Scenario**: Generate personalized contracts using external document services

            * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
            * **Integration**: Customer information flows to document generation API, completed contracts return to process
            * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
            * **Business Value**: Automated contract creation with legal template compliance and version control
          </Accordion>

          <Accordion title="Document Processing & OCR">
            **Scenario**: Process uploaded documents through external AI/OCR services

            * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
            * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
            * **Storage**: Processed documents and extracted data stored for business logic processing
            * **Business Value**: Automated document processing with intelligent data extraction capabilities
          </Accordion>

          <Accordion title="Report Generation & Analytics">
            **Scenario**: Generate business reports using external reporting services

            * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
            * **Integration**: Business metrics and KPIs sent to specialized reporting engines
            * **Storage**: Generated reports available for download and distribution workflows
            * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
          </Accordion>

          <Accordion title="CMS & Content Management">
            **Scenario**: Integrate with content management systems for file organization

            * **Process Flow**: Upload files → CMS integration → Organize and categorize content
            * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
            * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
            * **Business Value**: Centralized content management with automated workflow integration
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/platform-deep-dive/integrations/integration-designer">
          Learn more about Integration Designer

          <svg>
            <path />
          </svg>
        </a>

        <span>
          Major Enhancement
        </span>
      </div>
    </Card>

    ***

    ### **Resources Overrides**

    <Card title="Resources Overrides" icon="globe">
      <Tabs>
        <Tab title="Resources Overrides Overview">
          <Frame>
            ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
          </Frame>

          Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Localization Control" icon="language">
              Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
            </Card>

            <Card title="Centralized Management" icon="sitemap">
              Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
            </Card>

            <Card title="Selective Overriding" icon="check">
              Override only specific resources that need localization while inheriting all other updates from the main library
            </Card>

            <Card title="Export/Import Support" icon="arrows-rotate">
              Automatically include override configurations in project exports and imports for seamless environment management
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Business Benefits">
          <Steps>
            <Step title="Accelerate Global Expansion">
              Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
            </Step>

            <Step title="Maintain Compliance">
              Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
            </Step>

            <Step title="Preserve Investment">
              Continue receiving updates and improvements from headquarters without losing local customizations
            </Step>

            <Step title="Reduce Maintenance Overhead">
              Manage regional variations centrally instead of maintaining completely separate application instances
            </Step>
          </Steps>
        </Tab>

        <Tab title="Supported Resource Types">
          <CardGroup>
            <Card title="Process Overrides" icon="pipe">
              Customize business process logic while maintaining input/output compatibility and core workflow structure
            </Card>

            <Card title="Workflow Overrides" icon="diagram-project">
              Replace entire workflow implementations to adapt business rules for local requirements
            </Card>

            <Card title="Enumeration Overrides" icon="list">
              Localize value lists, dropdown options, and classification systems for regional variations
            </Card>

            <Card title="Runtime Resolution" icon="clock">
              Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Real-World Applications">
          <Accordion title="Multi-National Banking">
            **Scenario**: Global bank with country-specific loan approval processes

            * **Global Library**: Common loan application workflow with standard validation steps
            * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
            * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
          </Accordion>

          <Accordion title="Insurance Operations">
            **Scenario**: Insurance company operating across different regulatory environments

            * **Global Library**: Standard claims processing workflow and policy management
            * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
            * **Business Value**: Consistent global operations with local market adaptation and compliance
          </Accordion>

          <Accordion title="Manufacturing & Supply Chain">
            **Scenario**: Manufacturing company with different operational requirements per region

            * **Global Library**: Core production planning and inventory management processes
            * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
            * **Business Value**: Standardized operations with flexibility for local business practices and regulations
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/projects/resources#resources-overrides">
          Learn more about Resources Overrides

          <svg>
            <path />
          </svg>
        </a>

        <span>
          Major Enhancement
        </span>
      </div>
    </Card>

    ***

    ### **Active Policy Overrides**

    <Card title="Active Policy Overrides" icon="user-gear">
      <Tabs>
        <Tab title="Active Policy Overrides Overview">
          <Frame>
            ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
          </Frame>

          Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="User-Specific Policies" icon="user">
              Create individual policy overrides for specific users to test different builds independently
            </Card>

            <Card title="Role-Based Overrides" icon="users-gear">
              Apply policy overrides to entire roles for team-based testing and deployment strategies
            </Card>

            <Card title="Priority-Based Resolution" icon="scale-balanced">
              Handle conflicts when multiple overrides apply using configurable priority systems
            </Card>

            <Card title="Real-Time Switching" icon="arrows-rotate">
              Switch between different project versions instantly without deployment downtime
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Business Benefits">
          <Steps>
            <Step title="Independent Testing">
              Enable QA teams and developers to test different builds simultaneously without interfering with production users
            </Step>

            <Step title="Controlled Rollouts">
              Gradually deploy new features to specific user groups before full production release
            </Step>

            <Step title="Emergency Rollback">
              Quickly revert specific users to stable versions during incidents without affecting the entire system
            </Step>

            <Step title="Branch-Specific Development">
              Allow different teams to work with different development branches in shared environments
            </Step>
          </Steps>
        </Tab>

        <Tab title="Override Management">
          <CardGroup>
            <Card title="Policy Types" icon="gear">
              Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
            </Card>

            <Card title="Search & Filter" icon="magnifying-glass">
              Real-time search functionality to quickly locate specific user or role overrides
            </Card>

            <Card title="Activation Control" icon="toggle-on">
              Enable or disable overrides without deletion for temporary testing scenarios
            </Card>

            <Card title="Conflict Resolution" icon="scale-balanced">
              Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Real-World Scenarios">
          <Accordion title="Development Team Testing">
            **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates

            * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
            * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
            * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
          </Accordion>

          <Accordion title="Gradual Feature Rollout">
            **Scenario**: New premium features need testing with select customers before full release

            * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
            * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
            * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
          </Accordion>

          <Accordion title="Emergency Response">
            **Scenario**: Critical bug discovered in production affecting specific user workflows

            * **Override Setup**: Create high-priority role override for affected user groups
            * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
            * **Business Value**: Immediate incident response with minimal user impact and service continuity
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/projects/runtime/active-policy">
          Learn more about Active Policy Overrides

          <svg>
            <path />
          </svg>
        </a>

        <span>
          Major Enhancement
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="Persistence">
    Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.

    🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
    🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.

    ### **Workspaces (Multi-Tenant Architecture)**

    <Card title="Workspaces" icon="building-columns">
      <Tabs>
        <Tab title="Workspaces Overview">
          <Frame>
            ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
          </Frame>

          FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
        </Tab>

        <Tab title="Workspaces Key Features">
          <CardGroup>
            <Card title="Multi-Tenant Architecture" icon="building-columns">
              Logical separation of business contexts with shared infrastructure
            </Card>

            <Card title="Enhanced Access Control" icon="shield-check">
              Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
            </Card>

            <Card title="Data Isolation" icon="lock">
              Complete logical isolation between workspaces while enabling controlled resource sharing
            </Card>

            <Card title="User Groups & Roles" icon="users-gear">
              Simplified permission management through groups and workspace-specific roles
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Workspaces Benefits">
          <Steps>
            <Step title="Accelerated Onboarding">
              Onboard new business verticals in days instead of weeks with shared platform capabilities
            </Step>

            <Step title="Enhanced Governance">
              Implement fine-grained access control with workspace-specific roles and permissions
            </Step>

            <Step title="Operational Efficiency">
              Centralize platform upgrades, maintenance, and monitoring across all business units
            </Step>
          </Steps>
        </Tab>

        <Tab title="Workspaces Use Cases">
          <CardGroup>
            <Card title="Multi-National Operations" icon="globe">
              Separate workspaces for different countries/regions with shared global processes
            </Card>

            <Card title="Business Unit Separation" icon="building">
              Independent workspaces for retail, corporate, and investment banking divisions
            </Card>

            <Card title="Regulatory Compliance" icon="scale-balanced">
              Isolate processes subject to different regulatory requirements
            </Card>

            <Card title="Team-Based Development" icon="users">
              Enable different teams to work independently while sharing common resources
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/projects/workspaces">
          Learn more about Workspaces

          <svg>
            <path />
          </svg>
        </a>

        <span>
          Platform Evolution
        </span>
      </div>
    </Card>

    ***

    ### **FlowX.AI Database**

    <Card title="FlowX.AI Database" icon="server">
      <Tabs>
        <Tab title="FlowX.AI Database Overview">
          <Frame>
            <video />
          </Frame>

          FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
        </Tab>

        <Tab title="FlowX.AI Database Key Features">
          <CardGroup>
            <Card title="Data Persistence" icon="database">
              Store data that persists beyond process instances
            </Card>

            <Card title="MongoDB Operations" icon="code">
              Find, insert, and manipulate data using familiar MongoDB operations
            </Card>

            <Card title="Workflow Integration" icon="diagram-project">
              Seamlessly integrate with workflows through Data Source nodes
            </Card>

            <Card title="Document Collections" icon="folder-tree">
              Organize your data in structured collections
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="FlowX.AI Database Benefits">
          <Steps>
            <Step title="Share data between processes">
              Enable communication and data sharing between different process instances
            </Step>

            <Step title="Reduce external dependencies">
              Store operational data within FlowX.AI instead of building custom connectors
            </Step>

            <Step title="Enable new use cases">
              Build dashboards, caching solutions, and other applications that require persistent data
            </Step>

            <Step title="Simplify architecture">
              Keep your data within the FlowX.AI ecosystem for improved security and simplicity
            </Step>
          </Steps>
        </Tab>

        <Tab title="UI Integration">
          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
          </Frame>

          FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/platform-deep-dive/integrations/flowx-database">
          Learn more about FlowX.AI Database

          <svg>
            <path />
          </svg>
        </a>

        <span>
          New Feature
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="Rendering Improvements & UI/UX Enhancements">
    Enhanced user experience through improved components, better performance, and streamlined interface design.

    🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-uiux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
    📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
    🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.

    ### **Rendering Improvements & UI/UX Enhancements**

    <Card title="Rendering Improvements & UI/UX Enhancements" icon="palette">
      FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.

      ## Interface & Navigation Improvements

      <CardGroup>
        <Card title="Enhanced Grid Component" icon="grid">
          Improved performance, responsiveness, and customization options for data display and form organization
        </Card>

        <Card title="Navigation Areas Redesign" icon="compass">
          Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
        </Card>

        <Card title="Multi Actions Support" icon="arrow-left">
          Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
        </Card>

        <Card title="Permission-Based UI Editing" icon="shield-check" href="../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions">
          Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
        </Card>
      </CardGroup>

      ## Enhanced Form Controls & Components

      <CardGroup>
        <Card title="Input Type Code" icon="code" href="../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types">
          Specialized input component for code entry
        </Card>

        <Card title="Formatting Options" icon="paragraph">
          Advanced formatting capabilities for Input and Slider components
        </Card>

        <Card title="Switch Variants" icon="toggle-on" href="../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type">
          Enhanced switch component supporting both toggle and checkbox variants
        </Card>

        <Card title="Disabled Options on Selectors" icon="ban" href="../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options">
          Configure specific options as disabled while keeping them visible in dropdown lists
        </Card>
      </CardGroup>

      ## User Experience Enhancements

      <CardGroup>
        <Card title="Custom Loader" icon="arrows-rotate">
          Configurable loading indicators for improved user experience during data operations
        </Card>

        <Card title="Custom Expression Validators" icon="scale-balanced" href="../../../../5.1/docs/building-blocks/ui-designer/validators#custom-expression-validator">
          Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
        </Card>

        <Card title="File Upload Button Type" icon="cloud-arrow-up">
          Introduces a specialized button variant for file upload operations, supporting <strong>fill</strong>, <strong>ghost</strong>, and <strong>text</strong> types for flexible UI styling.
        </Card>

        <Card title="Copy Styles" icon="copy">
          Efficiently replicate styling across multiple UI components
        </Card>
      </CardGroup>

      ## Workflow & Analytics Improvements

      <CardGroup>
        <Card title="Analytics Enhancements" icon="chart-bar">
          Custom payload support for detailed user interaction tracking and business intelligence
        </Card>

        <Card title="Process End Handling" icon="flag">
          Improved user experience when processes complete or terminate
        </Card>

        <Card title="Template Management" icon="square">
          Streamlined template organization by consolidating functionality in Reusable Resources
        </Card>
      </CardGroup>
    </Card>

    ***

    ### **Forms in Collections**

    <Card title="Forms in Collections" icon="album-collection">
      A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.

      <video />

      ## Key Capabilities

      <CardGroup>
        <Card title="No Custom Development" icon="code">
          Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
        </Card>

        <Card title="Flexible Validation" icon="shield-check">
          Choose between individual item validation or bulk validation across all collection items
        </Card>

        <Card title="Two Saving Scenarios" icon="floppy-disk">
          Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
        </Card>
      </CardGroup>

      ## Common Use Cases Solved

      <Steps>
        <Step title="Dynamic Forms">
          Build forms that show different elements based on conditions without custom development
        </Step>

        <Step title="Repeatable Sections">
          Create forms with sections like adding multiple co-debtors, comments, or family members
        </Step>

        <Step title="Complex Data Entry">
          Handle arrays of objects with proper validation and data management
        </Step>

        <Step title="Real-time vs Batch Processing">
          Choose individual saves for real-time editing or bulk saves for form completion workflows
        </Step>
      </Steps>
    </Card>

    ***

    ### **Multi Select UI Component**

    <Card title="Multi Select UI Component" icon="list-check">
      <Tabs>
        <Tab title="Multi Select Overview">
          <Frame>
            ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
          </Frame>

          The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Multiple Selections" icon="check-double">
              Users can select multiple options from dropdown lists, with values stored as arrays
            </Card>

            <Card title="Flexible Display Options" icon="eye">
              Show selections as chips, comma-separated lists, or custom formats
            </Card>

            <Card title="Selection Limits" icon="hashtag">
              Configure maximum number of selectable options to control user input
            </Card>

            <Card title="Search & Filter" icon="magnifying-glass">
              Built-in search functionality to filter through large option lists
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Multi Select Use Cases">
          <Steps>
            <Step title="Skills & Competencies">
              Allow users to select multiple skills, qualifications, or areas of expertise
            </Step>

            <Step title="Categories & Tags">
              Enable selection of multiple categories, tags, or classification options
            </Step>

            <Step title="Product Features">
              Let customers choose multiple product features, services, or add-ons
            </Step>

            <Step title="Preferences & Settings">
              Capture user preferences where multiple options can be active simultaneously
            </Step>
          </Steps>
        </Tab>

        <Tab title="Configuration">
          <Frame>
            ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
          </Frame>

          Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.

          <Accordion title="Key Configuration Options">
            * **Max. Options Selectable**: Limit the number of selections
            * **Show selections**: Choose how selected items are displayed
            * **Search for options**: Enable filtering within large lists
            * **Has Clear**: Allow users to clear all selections at once
            * **Validation rules**: Min/max selections, required validations
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select">
          Learn more about Multi Select

          <svg>
            <path />
          </svg>
        </a>

        <span>
          New Component
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="AI Platform">
    New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.

    🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes

    ### **AI Nodes in Integration Designer**

    <Card title="AI Nodes in Integration Designer" icon="brain">
      <Tabs>
        <Tab title="AI Nodes Overview">
          <Frame>
            ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
          </Frame>

          FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
        </Tab>

        <Tab title="AI Text Operations">
          <CardGroup>
            <Card title="Text Transformation" icon="wand-magic-sparkles">
              Modify text tone, complexity or formatting for better clarity or style
            </Card>

            <Card title="Text Understanding" icon="brain">
              Analyze text to determine sentiment, topics, intent, language and named entities
            </Card>

            <Card title="Text Generation" icon="pen-nib">
              Generate new text such as summaries, completions, translations or paraphrases
            </Card>

            <Card title="Text Extraction" icon="filter">
              Extract structured information, keywords or metadata from text
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="AI Document Operations">
          <CardGroup>
            <Card title="Document Generation" icon="file-lines">
              Automatically build reports or complete templates based on given inputs
            </Card>

            <Card title="Document Extraction" icon="file-import">
              Identify and extract structured data, entities or metadata from documents
            </Card>

            <Card title="Document Understanding" icon="file-magnifying-glass">
              Analyze documents to extract meaning, topics, sentiment, or important information
            </Card>

            <Card title="Extract Text from Document" icon="file-code">
              Extract text content from documents (OCR, PDF text extraction)
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="AI Image & Data Operations">
          **Image Operations:**

          <CardGroup>
            <Card title="Image Description" icon="image">
              Generate captions or extract detailed information from visual content
            </Card>

            <Card title="Image Analysis" icon="eye">
              Recognize objects, emotions and scenes in images for contextual understanding
            </Card>
          </CardGroup>

          **Data Operations:**

          <CardGroup>
            <Card title="Data Enrichment" icon="database">
              Add annotations, context or relationships to enhance raw data value
            </Card>

            <Card title="Data Generation" icon="table">
              Produce synthetic or structured data using templates and logic-based rules
            </Card>

            <Card title="Data Transformation" icon="arrows-rotate">
              Clean, normalize, aggregate, or restructure datasets into usable formats
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          <AccordionGroup>
            <Accordion title="Intelligent Document Processing">
              * Extract data from invoices, contracts, and forms
              * Classify documents automatically
              * Validate extracted information against business rules
            </Accordion>

            <Accordion title="Customer Communication Analysis">
              * Analyze customer feedback sentiment
              * Extract key topics from support tickets
              * Generate personalized responses
            </Accordion>

            <Accordion title="Content Generation">
              * Create summaries of long documents
              * Translate content to multiple languages
              * Generate reports from structured data
            </Accordion>

            <Accordion title="Data Processing">
              * Enrich customer data with AI-derived insights
              * Transform unstructured data to structured formats
              * Generate test data for development
            </Accordion>
          </AccordionGroup>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes">
          Learn more about AI Node Types

          <svg>
            <path />
          </svg>
        </a>

        <span>
          New Feature
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="Info">
    ## **Additional information**

    <CardGroup>
      <Card title="Deployment Guidelines v5.1" icon="server" href="./deployment-guidelines-v5.1">
        Instructions for deploying FlowX.AI 5.1.0
      </Card>

      <Card title="Migration Guide (from v4.7.x)" icon="arrow-up-right-dots" href="./migrating-from-v4.7.x-to-5.1/migration-overview">
        Step-by-step guide for migrating from v4.7.x to v5.1.0
      </Card>
    </CardGroup>
  </Tab>
</Tabs>


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
  Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:

  * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
  * **Proactive quality improvements** identified through internal QA before reaching customers
  * **Customer issues** resolved with full business context
  * **Zero breaking changes** - fully compatible upgrade from 5.1.0

  This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.

    ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-21-compliance-achieved) — Full accessibility support across all web components\
    🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
    🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
    🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
    ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
    🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements

    ### **WCAG 2.1 compliance**

    <Card title="WCAG 2.1 compliance" icon="universal-access">
      <Tabs>
        <Tab title="Overview">
          **FlowX.AI is now WCAG 2.1 Level AA compliant**

          This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.

          ### Business value

          <CardGroup>
            <Card title="Government Compliance" icon="landmark">
              Meet accessibility requirements for government and public sector applications
            </Card>

            <Card title="Healthcare Standards" icon="hospital">
              Comply with healthcare industry accessibility regulations and standards
            </Card>

            <Card title="Financial Services" icon="building-columns">
              Satisfy financial sector requirements for inclusive digital experiences
            </Card>

            <Card title="Universal UX" icon="users">
              Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
            </Card>
          </CardGroup>

          ### What changed

          * All components now fully keyboard-accessible
          * Complete screen reader support with ARIA labels
          * Proper focus management across all interactions
          * Accessible error announcements and validation
          * Semantic HTML structure throughout
        </Tab>

        <Tab title="Key features">
          <CardGroup>
            <Card title="Auto-bindable ARIA Tags" icon="tag">
              Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
            </Card>

            <Card title="Keyboard Navigation" icon="keyboard">
              Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
            </Card>

            <Card title="Screen Reader Support" icon="audio-description">
              ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
            </Card>

            <Card title="UI Designer Integration" icon="sliders">
              Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Supported components">
          <Steps>
            <Step title="Form Elements">
              Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
            </Step>

            <Step title="Interactive Components">
              Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
            </Step>

            <Step title="Display Components">
              Messages and Images with semantic HTML structure and proper labeling
            </Step>

            <Step title="Platform Support">
              Complete implementation for Angular and React SDKs (iOS and Android in future releases)
            </Step>
          </Steps>
        </Tab>

        <Tab title="Implementation details">
          **28 Improvements Delivered:**

          <Accordion title="Angular SDK">
            * Custom keyboard navigation implementation
            * Focus management for Select/Multiselect components
            * Modal focus trap and restoration
            * Shift+Tab handling across form elements
            * Listbox keyboard operations
            * Table navigation improvements
            * Switch and checkbox accessibility
            * File preview focus indicators
            * Button Space key activation
            * Link focus outlines
            * Disabled element keyboard behavior
          </Accordion>

          <Accordion title="React SDK">
            * BaseUI Combobox implementation for Select/Multiselect
            * Keyboard navigation with clear buttons
            * Focus restoration after interactions
            * Outline theming for focus indicators
            * Modal auto-focus on open
            * Card accordion keyboard handling
            * Table row navigation
            * Option highlighting in dropdowns
          </Accordion>

          <Accordion title="UI Designer">
            * Accessibility configuration panel
            * Auto-bindable tags for all components
            * Label and description fields
            * Alt text management for images
            * ARIA attribute configuration
            * Accessibility section styling
            * Component-specific accessibility settings
          </Accordion>

          <Accordion title="Technical tasks completed">
            * Implemented BaseUI Combobox for Select/Multiselect
            * Custom keyboard navigation for Angular
            * React SDK keyboard navigation with clear button
            * Auto-bindable accessibility tags for all components
            * Accessibility configuration panel in UI Designer
            * Removed conflicting title attribute tooltips
            * Aligned Stepper accessibility between frameworks
            * Bind labels and descriptions to form fields
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <a href="../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/accessibility">
          Learn more about Accessibility Configuration

          <svg>
            <path />
          </svg>
        </a>

        <span>
          Major Achievement
        </span>
      </div>
    </Card>

    ***

    ### **Customer fixes**

    <Card title="Customer fixes" icon="user-headset">
      We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.

      <Accordion title="Action parameters lost on copy/paste">
        **Problem:**\
        When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.

        **Customer Impact:**

        * Development velocity significantly reduced
        * Risk of configuration errors during manual re-entry
        * Frustration with repetitive configuration work

        **Resolution:**\
        actionParamsMap now properly persists through copy/paste operations

        **Steps to reproduce (fixed):**

        1. Create send message node with Kafka action
        2. Configure topic and message parameters
        3. Copy and paste the node
        4. All configurations now preserved correctly

        **Customer Benefit:**\
        Faster workflow development with reduced configuration errors and improved developer experience.
      </Accordion>

      <Accordion title="Orphaned warnings block process deployments">
        **Problem:**\
        When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.

        **Customer Impact:**

        * Build pipelines blocked by stale warnings
        * Deployment delays requiring manual database cleanup
        * Process export/import operations failed
        * Development and testing workflows disrupted

        **Resolution:**\
        Warnings now cascade-delete automatically when parent actions are removed

        **Steps to reproduce (fixed):**

        1. Create action with subactions containing warnings
        2. Delete the parent action
        3. All child warnings now properly cleaned up

        **Customer Benefit:**\
        Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
      </Accordion>

      <Accordion title="Default application cannot be removed">
        **Problem:**\
        Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.

        **Customer Impact:**

        * Environment cleanup difficulties
        * Testing complications with unwanted default projects
        * Confusion about application lifecycle management

        **Resolution:**\
        Added proper runtime validation for application deletion operations

        **Error (Fixed):**

        ```json theme={"system"}
        {
          "status": 400,
          "message": "error.validation.runtime.application.not_found",
          "title": "Runtime project not found."
        }
        ```

        **Customer Benefit:**\
        Clean environment management with predictable application lifecycle operations.
      </Accordion>
    </Card>

    ***

    ### **Proactive quality improvements**

    <Card title="Proactive quality improvements" icon="sparkles">
      <Tabs>
        <Tab title="Overview">
          **Issues identified and resolved proactively**:

          ### Quality process

          <CardGroup>
            <Card title="Accessibility Audits" icon="clipboard-check">
              WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
            </Card>

            <Card title="Automated Testing" icon="robot">
              Continuous integration pipelines caught component behavior issues and rendering problems
            </Card>

            <Card title="Internal QA" icon="magnifying-glass">
              Manual testing uncovered edge cases in form interactions and modal behaviors
            </Card>

            <Card title="Code Reviews" icon="code-branch">
              Peer reviews identified potential stability issues in backend processing and dependency management
            </Card>
          </CardGroup>

          ### Distribution by category

          * **Keyboard Navigation**: Fixes across Angular and React
          * **Focus Management**: Fixes for modals, forms, and interactive elements
          * **Component Behavior**: Fixes for proper state handling and rendering
          * **Backend Stability**: Fixes for processing and dependency management
        </Tab>

        <Tab title="Angular SDK">
          <Accordion title="Keyboard navigation improvements">
            * Fixed listbox remaining open when pressing Shift+Tab
            * Fixed Shift+Tab not working on Select with search
            * Fixed Multiselect tab navigation moving to first element instead of next
            * Fixed Select input focus not working properly
            * Fixed Select list not scrolling during keyboard navigation
            * Fixed up/down arrow scrolling screen alongside option list
            * Fixed focus lost after loading new user task
            * Fixed focusable table content not reached from table header
            * Fixed Link in message focus missing outline
            * Fixed modal close button not focused automatically
            * Fixed file preview focus not highlighted and lost
            * Fixed button inside modal not working with Space key
          </Accordion>

          <Accordion title="Component Behavior Fixes">
            * Fixed Multiselect options list not opening
            * Fixed MultiSelect and link focusable when disabled
            * Fixed modal dismiss buttons not working with Space key
            * Fixed modal without close button not easily focusable
            * Fixed modal dismiss not focused automatically
            * Fixed Switch type checkbox focus not highlighted
            * Fixed Space pressed on card with accordion scrolling page
            * Fixed Switch with label position start focus issues
          </Accordion>
        </Tab>

        <Tab title="React SDK">
          <Accordion title="Keyboard Navigation Improvements">
            * Fixed outline from theme not applied to modal close button and links
            * Fixed Select selected option not highlighted in options list
            * Fixed Select search not filtering after selection
            * Fixed Input/textarea/select focus lost after using clear button
            * Fixed Tab focus moving inside collapsed card
            * Fixed table Tab navigation skipping rows
            * Fixed focusable table content not reached from table header
            * Fixed file preview retry focus not highlighted and lost
          </Accordion>

          <Accordion title="Component Behavior Fixes">
            * Fixed Select and link focusable when disabled
            * Fixed Switch type checkbox focus not highlighted
            * Fixed Datepicker clear icon focus not highlighted
            * Fixed modal dismiss not focused automatically
            * Fixed doc preview modal not closable with Enter or Space
            * Fixed button inside table focus not highlighted
            * Fixed Slider decimal numbers not rendered correctly
            * Fixed Substepper not rendered correctly
            * Fixed doc preview display mode showing inline
            * Fixed cards expandable before token reaches them
          </Accordion>
        </Tab>

        <Tab title="Designer & Backend">
          <Accordion title="UI Designer Improvements">
            * Fixed missing accessibility section on Link component
            * Fixed missing accessibility section on Image button
            * Fixed missing space in accessibility label and info icon
            * Fixed Alt text field disabled styling not applied
            * Fixed console errors when changing pages from header
            * Fixed Select/multiselect highlighted in preview and settings tabs
            * Fixed outline theming in enumerations and inputs
            * Fixed Workflows info points content not rendered correctly
            * Fixed Workflows tabs content not showing properly
            * Fixed padding missing on RUT UI Assets panel
          </Accordion>

          <Accordion title="Backend Stability Improvements">
            * Fixed wrong navigationTree response on overridden process
            * Fixed incorrect navigationTree for resource override details
            * Fixed error when trying to update dependency lib versions
            * Fixed error returned when updating dependency with override
            * Fixed no response on out topic for start process by name from Kafka
            * Fixed checkbox "Allow back to this action" status not loaded
            * Fixed empty screen when logging in without workspace access
            * Fixed Elasticsearch scheduled task errors with failed documents
            * Fixed services not logging when Liquibase crashing due to lock
          </Accordion>
        </Tab>
      </Tabs>

      <div>
        <span>
          Proactive Quality
        </span>
      </div>
    </Card>

    ***

    ### **Task management localization**

    <Card title="Task management localization" icon="language">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
          </Frame>

          * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
          * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**

          <Info>
            This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
          </Info>
        </Tab>

        <Tab title="Key features">
          <CardGroup>
            <Card title="FlowX Substitution Tags (51 Keys)" icon="tags">
              Complete set of substitution tags for task actions, statuses, history events, and UI elements
            </Card>

            <Card title="Table Grid Localization" icon="sliders">
              Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
            </Card>

            <Card title="Web Renderer Integration" icon="code">
              Angular and React renderers use system substitution tags on all task management texts
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="What's localized">
          **FlowX Substitution Tags (51 Keys):**

          * Table columns (title, stage, assignee, status, priority, last updated)
          * Process states (created, started, finished, failed, expired, etc.)
          * Task actions (assign, unassign, hold, unhold, execute, start)
          * Bulk operations (assign to, unassign all, hold all, etc.)
          * History events (task created, assigned, status changed, etc.)
          * User selection dialogs and UI states

          **Table Grid Localization**:

          * Filters (set, text, number, date with all operators)
          * Menus (column, context, aggregation, sorting)
          * Pagination (navigation, page size, row counts)
          * Data types (boolean, dates, numbers with formatting)
          * ARIA labels for accessibility
        </Tab>

        <Tab title="Implementation details">
          <Steps>
            <Step title="Set Container App Language">
              Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
            </Step>

            <Step title="Configure CMS Tags">
              Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
            </Step>

            <Step title="Use in Renderers">
              Web renderers automatically apply system substitution tags to all task management UI elements
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <div>
        <span>
          Localization
        </span>
      </div>
    </Card>

    <CardGroup>
      <Card title="Task Management Localization Guide" href="../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization" icon="book">
        Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
      </Card>

      <Card title="CMS Substitution Tags" href="../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags" icon="tags">
        Configure substitution tags in CMS for multi-language support
      </Card>
    </CardGroup>

    ***

    ### **AI Platform enhancements**

    <Card title="AI Platform enhancements" icon="robot">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.

          <CardGroup>
            <Card title="Multi-Agent System" icon="users">
              Enhanced agent communication and thread management for improved collaborative AI workflows
            </Card>

            <Card title="Conversation Stability" icon="message">
              Improved conversation handling with better error propagation and session management
            </Card>

            <Card title="AI Developer Tools" icon="wrench">
              Enhanced AI Developer capabilities with proper data model integration and expression generation
            </Card>

            <Card title="Document Intelligence" icon="file-text">
              Multi-page document generation support and improved content handling
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Key improvements">
          **Multi-Agent Conversation Management:**

          * Enhanced conversation thread handling with proper parent action status updates
          * Improved backend support for adding new messages on agent threads
          * Better session management with new session button in Command Center
          * Context switching prevention during execution plan generation

          **AI Developer Enhancements:**

          * Fixed data model integration for expressions and business rules generation
          * Improved action target saving and destination setting
          * Enhanced execution plan editing from user prompts
          * Better handling of empty execution plans

          **Error Handling & Stability:**

          * Graceful error propagation from internal AI agent operations
          * Improved CORS headers for document object downloads
          * Enhanced telemetry support for debugging and monitoring
          * Better handling of plan enhancement patches

          **Document & Content Features:**

          * Multi-page document generation support in AI nodes
          * Source selector component for image and document inputs
          * Improved messaging system for AI agents in command center
          * Enhanced UI feedback for AI-generated resources
        </Tab>

        <Tab title="Technical improvements">
          **Backend Enhancements:**

          * Continuous patching support for action contexts during execution
          * Improved navigation tree responses for overridden processes
          * Enhanced dependency management for library overrides
          * Better error handling and logging across AI services

          **Frontend Improvements:**

          * Fixed target selector closing behavior in implementation threads
          * Improved preview mode handling after developer changes
          * Enhanced command center messaging and error display
          * Better UI state management for AI workflow interactions

          **Integration Updates:**

          * CORS headers properly configured for GraphQL object downloads
          * Process task destinations automatically set to current process
          * Improved integration between AI agents and execution plans
          * Enhanced audit logging for resource overrides
        </Tab>
      </Tabs>

      <div>
        <span>
          AI Platform
        </span>
      </div>
    </Card>

    ***

    ### **Platform enhancements**

    <Card title="Platform enhancements" icon="server">
      <Tabs>
        <Tab title="Infrastructure">
          <CardGroup>
            <Card title="SSE Disconnect Handling" icon="plug">
              Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
            </Card>

            <Card title="Resource Overrides Audit" icon="file-shield">
              Implemented audit logs for library resource overrides to track configuration changes
            </Card>

            <Card title="Security Updates" icon="shield-check">
              Fixed high vulnerabilities in Designer 5.1.x and main branch
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Renderer Enhancements">
          <CardGroup>
            <Card title="System Substitution Tags" icon="code">
              Web renderers now use system substitution tags on all task management texts
            </Card>

            <Card title="Outline Theming" icon="palette">
              Enhanced outline and select/multiselect option highlight theming for visual consistency
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Technical Improvements">
          **Code Quality:**

          * Eliminated deprecated code for Kafka start process
          * Improved error handling for Elasticsearch document updates
          * Enhanced dependency management for library overrides
          * Better logging and error reporting across services

          **Performance:**

          * Optimized SSE connection handling
          * Improved query performance for navigation tree
          * Better resource management in long-running processes
        </Tab>
      </Tabs>

      <div>
        <span>
          Platform Updates
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    ### Known issues

    <Warning>
      The following items are in progress or backlog for future releases:

      * Android and iOS accessibility properties implementation
      * Additional Select component refinements
      * UI Designer padding optimizations
    </Warning>

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and critical bug fixes
    * Accessibility enhancements for mobile platforms
    * Performance optimizations

    Major new features are planned for future releases in the 5.x series. See the [5.2.0 Tech Preview](../v5.2.0-tech-preview/v5.2.0-tech-preview) for upcoming capabilities.
  </Tab>
</Tabs>


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
  Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:

  * Numerous bug fixes addressing reported and internally identified issues
  * New features and enhancements to various platform components
  * Platform tasks focused on infrastructure and overall stability
  * No breaking changes — fully compatible upgrade from 5.1.1
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.

    🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
    ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
    🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements

    ***

    ### **Bug fixes**

    <Card title="Bug fixes" icon="bug">
      <Tabs>
        <Tab title="Customer fixes">
          Issues resolved based on customer feedback:

          <Accordion title="Authorization service configuration">
            **Problem:**\
            Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.

            **Resolution:**\
            Fixed configu gration parameter mapping for service account client secret in Authorization service
          </Accordion>

          <Accordion title="Token state changes on back navigation">
            **Problem:**\
            When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.

            **Resolution:**\
            Fixed token state management during back navigation to preserve correct state
          </Accordion>

          <Accordion title="Action parameters not copied on node copy">
            **Problem:**\
            When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.

            **Resolution:**\
            Fixed actionParamsMap persistence through copy/paste operations
          </Accordion>

          <Accordion title="Permissions updated incorrectly during action execution">
            **Problem:**\
            hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.

            **Resolution:**\
            Fixed permission rule handling during action execution
          </Accordion>

          <Accordion title="Subprocess data mapping issues">
            **Problem:**\
            Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.

            **Resolution:**\
            Fixed data mapping behavior for subprocess start actions
          </Accordion>

          <Accordion title="Forms in collections - action not found">
            **Problem:**\
            When saving data from outside collection with forms to submit, actions were not found correctly.

            **Resolution:**\
            Fixed action resolution for forms inside collections
          </Accordion>
        </Tab>

        <Tab title="AI Platform fixes">
          <Accordion title="AI Designer improvements">
            * Fixed no feedback when uploading large documents in command center
            * Fixed targets for business rules never being set by planner
            * Fixed file upload limit lower than 3MB
            * Fixed missing messages on Keep/Discard buttons for UI and BR
            * Fixed Save & Close button not working in Data Model modal
            * Fixed DM keys not created after keeping UI
            * Fixed table key appearing as mapped when Data Model is empty
            * Fixed pip window being clipped
            * Fixed Submit prompt button color not indicating active state
            * Fixed source not indicating uploaded document for some Plan actions
            * Fixed UI outcome duplication until connected-graph keep method finishes
            * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
            * Fixed command center not reopenable after closing in developer preview mode
            * Fixed planner sample data import crashes
            * Fixed business logic targets not correctly stored in execution plan
          </Accordion>
        </Tab>

        <Tab title="Renderer fixes">
          <Accordion title="Web renderer improvements">
            * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
            * Fixed card collapsing when next nav area is modal (Angular & React)
            * Fixed card not expandable after finishing subprocess started from it (Angular & React)
            * Fixed loader missing or not fully shown in React
            * Fixed message icon and text rendered on different rows when width fill in React
            * Fixed collection prototype shown when collection source array doesn't exist in React
            * Fixed broken image rendered when missing url or base64 image in React
            * Fixed switch component knob and container alignment in React
            * Fixed multi select search not filtering available options in React SDK
            * Fixed custom component keys duplicated in action body (React & Angular)
          </Accordion>

          <Accordion title="Task Manager fixes">
            * Fixed Task Manager theming not applied in Angular
            * Fixed Task Manager header theming not applied in React
            * Fixed assignee dropdown list and placeholder not displayed in React
          </Accordion>

          <Accordion title="Reusable templates fixes">
            * Fixed custom body being null at runtime for Reusable templates actions
          </Accordion>
        </Tab>

        <Tab title="Platform & Data fixes">
          <Accordion title="Data model and mappers">
            * Fixed input/output parameters not deleted after updating parameters
            * Fixed Go to reference button redirecting incorrectly
            * Fixed parameters items deleted when updating Project Data Model object
          </Accordion>

          <Accordion title="Process Designer">
            * Fixed retry token button available for inactive tokens
            * Fixed missing save action button when opening action config from UI designer
          </Accordion>

          <Accordion title="Platform stability">
            * Fixed advancing errors in partition event table
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **New features**

    <Card title="New features" icon="sparkles">
      <Tabs>
        <Tab title="AI Platform">
          <Card title="Data Model Generation" icon="database">
            Generate Data Model for tables and table columns from AI Designer
          </Card>
        </Tab>

        <Tab title="Renderers">
          <CardGroup>
            <Card title="Android Accessibility" icon="mobile">
              Accessibility properties from UI Designer now supported in Android renderer
            </Card>

            <Card title="Substitution Tags in Selectors" icon="tags">
              Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
            </Card>

            <Card title="Template Caching" icon="bolt">
              Improved caching for reusable templates at runtime
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Platform improvements**

    <Card title="Platform improvements" icon="server">
      <Tabs>
        <Tab title="Infrastructure">
          <CardGroup>
            <Card title="Dgraph Upgrade" icon="database">
              Bring dgraph to flowx-release
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Performance & Optimization">
          <Card title="Designer Static Assets" icon="file">
            Make designer nginx use compression & caching for static assets
          </Card>
        </Tab>
      </Tabs>
    </Card>
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).

    ### Known issues

    <Warning>
      The following items are in progress or backlog for future releases:

      * Task Manager theming issues in Angular and React
      * Task Manager assignee dropdown display issues in React
      * Custom component key duplication in action body
    </Warning>

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
    * Additional renderer enhancements
  </Tab>
</Tabs>


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:

  * Numerous bug fixes addressing reported and internally identified issues
  * Improvements and enhancements to various platform components
  * Platform tasks focused on infrastructure and overall stability
  * No breaking changes — fully compatible upgrade from 5.1.2
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.

    ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
    ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
    ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
    🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
    🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates

    ***

    ### **Improvements and enhancements**

    <Card title="Improvements and enhancements" icon="sparkles">
      <Tabs>
        <Tab title="Renderers">
          <CardGroup>
            <Card title="iOS Accessibility" icon="mobile">
              VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="AI Platform">
          <CardGroup>
            <Card title="Data Model Generation for Tables" icon="table">
              Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
            </Card>

            <Card title="Data Model Generation for Table Columns" icon="table-columns">
              Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Performance improvements**

    <Card title="Performance improvements" icon="gauge-high">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.1.3 delivers significant performance improvements to the process engine

          <CardGroup>
            <Card title="Optimized Writes" icon="database">
              Smart change detection skips unnecessary database writes when param\_values unchanged
            </Card>

            <Card title="Reduced DB Calls" icon="arrows-minimize">
              N+1 query fixes and batch loading significantly reduce database round trips
            </Card>

            <Card title="Request Caching" icon="memory">
              Request-scoped caching for frequently accessed runtime configuration
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Key optimizations">
          <Accordion title="ProcessInstance param_values Optimization">
            Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:

            * **Change Detection**: Skip database writes when param\_values unchanged
            * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
          </Accordion>

          <Accordion title="Runtime Improvements - Reduced DB Calls">
            **Optimizations Implemented:**

            * Improved batch loading and caching to reduce redundant queries
            * Streamlined process initiation
            * Enhanced batching for database writes
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Bug fixes**

    <Card title="Bug fixes" icon="bug">
      <Tabs>
        <Tab title="Customer fixes">
          Issues resolved based on customer feedback:

          <Accordion title="Task Manager View Not Updating">
            **Problem:**\
            When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.

            **Resolution:**\
            Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
          </Accordion>

          <Accordion title="Forms in Collections - Backend Keys Calculation">
            **Problem:**\
            When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.

            **Resolution:**\
            Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
          </Accordion>

          <Accordion title="Variables Reset on Config Update">
            **Problem:**\
            Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.

            **Resolution:**\
            Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
          </Accordion>

          <Accordion title="Build Export Timeout">
            **Problem:**\
            When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.

            **Resolution:**\
            Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
          </Accordion>
        </Tab>

        <Tab title="Designer fixes">
          <Accordion title="Table Row Deletable with Backspace in RUT">
            **Problem:**\
            In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.

            **Resolution:**\
            Fixed keyboard handling to prevent accidental table row deletion via backspace key.
          </Accordion>
        </Tab>

        <Tab title="Renderer fixes">
          <Accordion title="Android Upload Action Payload Missing">
            **Problem:**\
            Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.

            **Resolution:**\
            Fixed payload handling to include all required data in upload action execution.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Platform improvements**

    <Card title="Platform improvements" icon="server">
      <Tabs>
        <Tab title="Infrastructure">
          <CardGroup>
            <Card title="Connector Topic Pattern" icon="message">
              Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="AI Platform">
          <CardGroup>
            <Card title="Streaming Client Library" icon="code">
              Implemented client library for invoking the run AI node with streaming support for conversational API
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>
    </Card>
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### New configuration options

    <Info>
      **Optional**: New environment variable available for process-engine
    </Info>

    | Variable                        | Description                                                                           | Default                                        |
    | ------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------- |
    | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
    * Additional renderer enhancements
  </Tab>
</Tabs>


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:

  * Numerous bug fixes addressing reported and internally identified issues
  * Improvements and enhancements to various platform components
  * Platform tasks focused on infrastructure and overall stability
  * No breaking changes — fully compatible upgrade from 5.1.3
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.

    🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
    ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates

    ***

    ### **Bug Fixes**

    <Card title="Bug Fixes" icon="bug">
      <Tabs>
        <Tab title="Customer fixes">
          Issues resolved based on customer feedback:

          <Accordion title="Form validators do not work inside collection prototypes">
            **Summary:**

            Validators applied to forms within collection prototypes are not triggered as expected.
          </Accordion>

          <Accordion title="Project editor could modify access permissions">
            **Summary:**

            Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
          </Accordion>

          <Accordion title="Subprocess UI still shown after subprocess is finished">
            **Summary:**

            In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Platform Improvements**

    <Card title="Platform Improvements" icon="server">
      <Tabs>
        <Tab title="Infrastructure">
          <CardGroup>
            <Card title="Kafka environment variables alignment" icon="server">
              Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
            </Card>

            <Card title="Config params cache improvements" icon="server">
              New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
            </Card>

            <Card title="Project editor permissions update" icon="shield-halved">
              `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
            </Card>

            <Card title="Advancing partition counter fix" icon="gauge-high">
              Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
    * Additional renderer enhancements
  </Tab>
</Tabs>


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:

  * Fixes for process loop rendering issues in the Angular renderer
  * Fix for subprocess output data not being returned from embedded processes
  * No breaking changes — fully compatible upgrade from 5.1.4
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.

    🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios

    ***

    ### **Bug Fixes**

    <Card title="Bug Fixes" icon="bug">
      <Tabs>
        <Tab title="Renderer fixes">
          Issues resolved in the Angular renderer:

          <Accordion title="Validation shown without user interaction on process loop">
            **Summary:**

            When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
          </Accordion>

          <Accordion title="Action executed continuously on process loop">
            **Summary:**

            When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
          </Accordion>
        </Tab>

        <Tab title="Process engine fixes">
          <Accordion title="Subprocess not returning output from embedded process">
            **Summary:**

            When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
    * Additional renderer enhancements
  </Tab>
</Tabs>


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:

  * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
  * Data mappers autocomplete fix for values not loading
  * Process engine fix for advancing getting stuck on pod crash with multiple partition events
  * Kafka health check fix for reporting UP despite consumer DNS failure
  * New health indicator for runtime MongoDB connection
  * Connection leak fix in application-manager export/import operations
  * Improved retry mechanism with configurable exponential backoff
  * Security patches and dependency upgrades
  * No breaking changes — fully compatible upgrade from 5.1.5
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.

    🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes

    🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches

    ***

    ### **Bug Fixes**

    <Card title="Bug Fixes" icon="bug">
      <Tabs>
        <Tab title="Renderer fixes (React)">
          Issues resolved in the React renderer:

          <Accordion title="Clear icon present and clickable on disabled input/textarea">
            **Summary:**

            When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
          </Accordion>

          <Accordion title="Options list not shown when selectors are inside modal">
            **Summary:**

            When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
          </Accordion>

          <Accordion title="Datepicker calendar shown behind modal">
            **Summary:**

            When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
          </Accordion>

          <Accordion title="Slider min/max value not set when loading a screen">
            **Summary:**

            When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
          </Accordion>

          <Accordion title="Slider default value not set with multiple sliders on same page">
            **Summary:**

            When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
          </Accordion>

          <Accordion title="Task management assignee clear icon clickable when disabled">
            **Summary:**

            In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
          </Accordion>

          <Accordion title="Input, select, datepicker, textarea, and table filters have incorrect inner outline">
            **Summary:**

            Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
          </Accordion>

          <Accordion title="Data mappers autocomplete values not loading">
            **Summary:**

            Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
          </Accordion>
        </Tab>

        <Tab title="Renderer fixes (Angular + React)">
          Issues resolved in both Angular and React renderers:

          <Accordion title="Card height does not update when accordion is collapsed">
            **Summary:**

            When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
          </Accordion>

          <Accordion title="Focus outline appears when interacting with card/file preview accordion">
            **Summary:**

            When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
          </Accordion>

          <Accordion title="Button icon not correctly rendered">
            **Summary:**

            When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
          </Accordion>
        </Tab>

        <Tab title="Process engine fixes">
          <Accordion title="Advancing gets stuck when multiple events are available for one partition and pod crashes">
            **Summary:**

            When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
          </Accordion>

          <Accordion title="Kafka health check reported UP despite consumer DNS failure">
            **Summary:**

            The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
          </Accordion>

          <Accordion title="Health indicator for runtime MongoDB connection">
            **Summary:**

            A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
          </Accordion>
        </Tab>

        <Tab title="Application manager fixes">
          <Accordion title="Theme not imported during build import">
            **Summary:**

            When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
          </Accordion>

          <Accordion title="Connection leak in export/import services">
            **Summary:**

            During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Platform Improvements**

    <Card title="Platform Improvements" icon="wrench">
      <Tabs>
        <Tab title="Process engine">
          <Accordion title="Configurable retry mechanism with exponential backoff">
            **Summary:**

            The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.

            New environment variables for the `process-engine`:

            | Environment Variable        | Description                                                | Default Value |
            | --------------------------- | ---------------------------------------------------------- | ------------- |
            | `FLOWX_RETRY_MAX_RETRIES`   | Maximum retry attempts (total = max + 1 including initial) | `9`           |
            | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds                      | `10`          |
            | `FLOWX_RETRY_MAX_DELAY_MS`  | Maximum backoff delay cap in milliseconds                  | `200`         |

            <Tip>
              Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
            </Tip>
          </Accordion>
        </Tab>

        <Tab title="Other improvements">
          <Accordion title="Removed deprecated access rights endpoint">
            **Summary:**

            A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
          </Accordion>

          <Accordion title="Security patches">
            This release includes security patches across all platform components to address known vulnerabilities.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
    * Additional renderer enhancements
  </Tab>
</Tabs>


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:

  * Fix for build import issues with manifest (reimport failures)
  * Security patches
  * No breaking changes, fully compatible upgrade from 5.1.6
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.

    🐛 [**Bug Fixes**](#bug-fixes) — Build import fix

    🔧 [**Platform Improvements**](#platform-improvements) — Security patches

    ***

    ### **Bug Fixes**

    <Card title="Bug Fixes" icon="bug">
      <Tabs>
        <Tab title="Application manager fixes">
          <Accordion title="Build reimport failures with manifest issues">
            **Summary:**

            When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***

    ### **Platform Improvements**

    <Card title="Platform Improvements" icon="wrench">
      <Tabs>
        <Tab title="Other improvements">
          <Accordion title="Security patches">
            This release includes security patches across platform components to address known vulnerabilities.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
  </Tab>
</Tabs>


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:

  * Security patches and dependency upgrades
  * No breaking changes — fully compatible upgrade from 5.1.7
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.8 delivers stability improvements across the platform.

    🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades

    ***

    ### **Platform Improvements**

    <Card title="Platform Improvements" icon="wrench">
      <Tabs>
        <Tab title="Other improvements">
          <Accordion title="Security patches">
            This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
  </Tab>
</Tabs>


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

<Info>
  This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.
</Info>

<Card title="Release Highlight" icon="star">
  **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:

  * Reusable UI template mapping and Designer fixes
  * Android renderer fixes
  * Security patches and dependency upgrades
  * No breaking changes — fully compatible upgrade from 5.1.8
</Card>

***

**What's new? 🆕**

<Tabs>
  <Tab title="Highlights">
    FlowX.AI 5.1.9 delivers stability improvements across the platform.

    🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades

    ***

    ### **Platform Improvements**

    <Card title="Platform Improvements" icon="wrench">
      <Tabs>
        <Tab title="Bug fixes">
          <Accordion title="Notable bug fixes">
            * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
            * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
            * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
          </Accordion>
        </Tab>

        <Tab title="Other improvements">
          <Accordion title="Security patches">
            This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
          </Accordion>
        </Tab>
      </Tabs>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    <Info>
      **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade Path" icon="arrow-up-right-dots">
        Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
      </Card>

      <Card title="Component Compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
      </Card>
    </CardGroup>

    ### Deployment information

    <Info>
      Standard deployment procedures apply. No special migration steps required for this maintenance release.
    </Info>

    For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).

    ### What's next

    **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:

    * Security patches and vulnerability fixes
    * Stability improvements and bug fixes
    * Performance optimizations
  </Tab>
</Tabs>


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2



<Info>
  After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Component versions

| Component                  | 5.2.0       | 5.1.1   | 5.1.0   | 5.0.0  | 4.7.9   | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5   |
| -------------------------- | ----------- | ------- | ------- | ------ | ------- | ------ | ------ | ------ | ------- |
| **process-engine**         | **10.12.0** | 9.64.3  | 9.63.0  | 9.29.2 | 8.24.1  | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin**                  | **10.12.0** | 9.66.5  | 9.65.0  | 9.25.2 | 7.18.4  | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2  |
| **designer**               | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1  |
| **cms-core**               | **10.7.0**  | 9.36.3  | 9.35.0  | 9.21.2 | 5.11.1  | 5.10.3 | 5.9.2  | 5.8.2  | 5.5.1   |
| **scheduler-core**         | **10.4.1**  | 9.26.1  | 9.25.0  | 9.12.0 | 5.7.1   | 5.6.2  | 5.5.2  | 5.4.0  | 5.1.1   |
| **events-gateway**         | **10.4.1**  | 9.26.1  | 9.25.0  | 9.12.0 | 5.7.1   | 5.6.2  | 5.5.2  | 5.4.0  | 5.1.1   |
| **notification-plugin**    | **10.7.0**  | 9.29.1  | 9.28.0  | 9.14.2 | 6.8.1   | 6.7.2  | 6.6.2  | 6.5.0  | 6.2.1   |
| **document-plugin**        | **10.6.0**  | 9.35.1  | 9.34.0  | 9.17.2 | 6.10.1  | 6.9.2  | 6.8.2  | 6.7.0  | 6.4.1   |
| **task-management-plugin** | **10.7.0**  | 9.34.2  | 9.33.0  | 9.14.2 | 7.9.2   | 7.8.2  | 7.7.2  | 7.6.0  | 7.3.1   |
| **data-search**            | **10.4.1**  | 9.23.1  | 9.22.0  | 9.12.1 | 4.7.1   | 4.6.2  | 4.5.2  | 4.4.0  | 4.1.1   |
| **audit-core**             | **10.6.0**  | 9.30.1  | 9.29.1  | 9.15.2 | 6.8.1   | 6.7.2  | 6.6.2  | 6.5.0  | 6.1.1   |
| **advancing-controller**   | **10.4.1**  | 9.25.1  | 9.24.0  | 9.11.0 | 4.7.1   | 4.6.2  | 4.6.2  | 4.4.0  | 4.1.1   |
| **integration-designer**   | **10.8.0**  | 9.50.0  | 9.49.1  | 9.26.2 | 2.16.1  | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0   |
| **application-manager**    | **10.11.0** | 9.73.6  | 9.72.0  | 9.27.3 | 2.23.1  | 2.22.3 | 2.21.2 | 2.2    |         |
| **runtime-manager**        | **10.11.0** | 9.73.6  | 9.72.0  | 9.27.3 | 2.23.1  | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2  |
| **data-sync**              | **10.3.1**  | 9.22.1  | 9.21.0  | 9.11.0 | 2.10.2  | 2.9.2  | 2.8.1  | 2.7.1  | 2.4.1   |
| **authorization-system**   | **10.7.0**  | 9.34.2  | 9.33.0  | 9.14.2 | -       | -      | -      | -      | -       |
| **nosql-db-runner**        | **10.4.1**  | 9.22.1  | 9.21.0  | 9.11.0 | -       | -      | -      | -      | -       |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component                     | 5.2.0       | 5.1.1   | 5.1.0   | 5.0.0  | 4.7.9   | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  |
| ----------------------------- | ----------- | ------- | ------- | ------ | ------- | ------ | ------ | ------ | ------ |
| **@flowx/angular-sdk**        | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme**      | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk**          | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme**        | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit**   | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk**           | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme**         | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer**              | **10.0.0**  | 9.0.5   | 9.0.4   | 9.0.0  | 4.0.29  | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer**          | **10.0.0**  | 9.0.3   | 9.0.2   | 9.0.0  | 4.0.29  | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component            | 5.2.0  | 5.1.1  | 5.1.0  | 5.0.0  | 4.7.9  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  |

### AI Platform

| Component                       | 5.2.0      | 5.1.1 | 5.1.0 | 5.0.0  | 4.7.9  | 4.7.8  | 4.7.7  | 4.7.6  | 4.7.5  |
| ------------------------------- | ---------- | ----- | ----- | ------ | ------ | ------ | ------ | ------ | ------ |
| **ai-assistant**                | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3  | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform**                 | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6  | 1.4.6  | 1.4.5  | 1.4.5  | 1.4.3  |
| **ai-platform-ai-developer**    | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-agents**          | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-conversations**   | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-models**          | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-tenants**         | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-planner**         | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-ai-analyst**      | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-ai-designer**     | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-agent-builder**   | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |
| **ai-platform-binaries**        | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      | -      | -      |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.2.0            | Keycloak             | 26+                |
| 5.2.0            | Kafka                | 3.8 - 3.9          |
| 5.2.0            | PostgreSQL           | 16 - 17            |
| 5.2.0            | Oracle Database      | 21c, 23ai          |
| 5.2.0            | MongoDB              | 7 - 8              |
| 5.2.0            | Redis                | 7.4 - 8.0          |
| 5.2.0            | Elasticsearch        | 8 - 9              |
| 5.2.0            | Angular (Web SDK)    | 19.2               |
| 5.2.0            | React (Web SDK)      | 18.x               |

<Warning>
  Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:

  * Keycloak versions older than 26
  * Kafka versions older than 3.8
  * Redis versions older than 7.4
</Warning>

## New in v5.2.0

### Key infrastructure updates

<CardGroup>
  <Card title="SpiceDB Upgrade" icon="database">
    Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability
  </Card>

  <Card title="Security Enhancements" icon="shield">
    Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities
  </Card>

  <Card title="Accessibility Support" icon="universal-access">
    Enhanced renderer components with comprehensive WCAG 2.1 compliance features
  </Card>

  <Card title="Python IDE Features" icon="code">
    Added autocomplete and IntelliSense support in business rules editors
  </Card>

  <Card title="Parallel Workflow Branches" icon="code-branch">
    Support for concurrent execution paths in Integration Designer workflows
  </Card>

  <Card title="Workflow Partitioning & Archiving" icon="database">
    Time-based partitioning and automatic archiving for Integration Designer workflow instances
  </Card>
</CardGroup>

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

<Info>
  For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
</Info>

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

<Info>
  For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.
</Info>

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

<Note>
  Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.
</Note>

#### New variables to add

| Variable                                               | Default Value | Description                                                        |
| ------------------------------------------------------ | ------------- | ------------------------------------------------------------------ |
| `FLOWX_DATA_PARTITIONING_ENABLED`                      | `false`       | Enable or disable workflow instance partitioning                   |
| `FLOWX_DATA_PARTITIONING_INTERVAL`                     | `MONTH`       | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`)     |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`            | `false`       | Enable or disable automatic archiving of old partitions            |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3`           | Number of intervals to retain before archiving                     |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`     | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

<Info>
  **Workflow partitioning configuration:**

  * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
  * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
  * **Archiving schedule**: The cron expression controls when the archiving process runs
  * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving
</Info>

<Warning>
  Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.
</Warning>

### Advancing controller improvements

<Note>
  Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.
</Note>

#### Variables to remove & replace

| Remove This Variable         | Replace With                                     |
| ---------------------------- | ------------------------------------------------ |
| `ADVANCING_THREADS`          | `ADVANCING_PICKINGTHREADS` (default: `1`)        |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable                                    | Default Value | Description                                                    |
| ------------------------------------------- | ------------- | -------------------------------------------------------------- |
| `ADVANCING_PROCESSINGTHREADS`               | `20`          | Number of threads for parallel processing of advancing events  |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true`        | Block picking operations when no worker threads are available  |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE`      | `20`          | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable                       | Current Value | New Value | Reason                                          |
| ------------------------------ | ------------- | --------- | ----------------------------------------------- |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100`         | `50`      | Optimized pause duration for better performance |

<Info>
  **How the new advancing controller works:**

  * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.

  * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.

  * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.

  * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.
</Info>


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

<Tabs>
  <Tab title="Accessibility & UX">
    Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.

    ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
    🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality

    ### **Accessibility enhancements**

    <Card title="Accessibility enhancements" icon="universal-access">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
          </Frame>

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
          </Frame>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Accessibility Configuration Panel" icon="sliders">
              Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
            </Card>

            <Card title="Auto-bindable Tags" icon="tag">
              Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
            </Card>

            <Card title="Keyboard Navigation" icon="keyboard">
              Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
            </Card>

            <Card title="Screen Reader Support" icon="audio-description">
              Use screen readers with ARIA labels, descriptions, and live regions on all components
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Supported Components">
          <Steps>
            <Step title="Form Elements">
              Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
            </Step>

            <Step title="Interactive Components">
              Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
            </Step>

            <Step title="Display Components">
              Messages and Images with alt text support and semantic HTML structure
            </Step>

            <Step title="Cross-Platform Support">
              Web (Angular/React), iOS, and Android platforms
            </Step>
          </Steps>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="WCAG Compliance" icon="scale-balanced">
              Build applications that meet WCAG 2.1 Level AA standards for web accessibility
            </Card>

            <Card title="Inclusive Design" icon="users">
              Make your applications usable for people with diverse abilities and assistive technology users
            </Card>

            <Card title="Improved User Experience" icon="star">
              Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
            </Card>

            <Card title="Regulatory Compliance" icon="shield-check">
              Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <span>
          Major Enhancement
        </span>
      </div>
    </Card>

    ***

    ### **New workflow side panel**

    <Card title="New workflow side panel" icon="sidebar">
      <Tabs>
        <Tab title="Overview">
          The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
          </Frame>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Drag & Drop" icon="hand">
              Add and organize workflow nodes with drag-and-drop functionality
            </Card>

            <Card title="Improved Organization" icon="folder-tree">
              Group nodes logically with expandable/collapsible sections
            </Card>

            <Card title="Search & Filter" icon="magnifying-glass">
              Find nodes instantly with quick search functionality
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <span>
          UI/UX Enhancement
        </span>
      </div>
    </Card>

    ***
  </Tab>

  <Tab title="Data & Security">
    Enhanced data management and security features for FlowX Database and business rules.

    🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
    🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance

    ### **FlowX database sensitive data**

    <Card title="FlowX database sensitive data" icon="shield-halved">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Automatic Data Masking" icon="eye-slash">
              Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
            </Card>

            <Card title="Project Data Model Integration" icon="database">
              Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
            </Card>

            <Card title="Developer-Friendly" icon="code">
              Access full data at runtime while maintaining security in design-time interfaces
            </Card>

            <Card title="Audit Trail Protection" icon="file-shield">
              Mask sensitive data in workflow output logs and operational documents
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Protected Areas">
          <Steps>
            <Step title="Documents Page">
              Sensitive attributes are masked when viewing FlowX Database documents in the designer
            </Step>

            <Step title="Test Operations Pages">
              Database operation testing interfaces automatically hide sensitive data
            </Step>

            <Step title="Workflow Console">
              Console logs and output panels mask sensitive information from FlowX Database responses
            </Step>

            <Step title="Full Runtime Access">
              Applications have full access to sensitive data at runtime - protection is design-time only
            </Step>
          </Steps>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="GDPR Compliance" icon="scale-balanced">
              Meet data protection requirements by preventing sensitive data exposure in design tools
            </Card>

            <Card title="Security by Design" icon="lock">
              Sensitive data protection is automatic once attributes are marked in Project Data Model
            </Card>

            <Card title="Developer Productivity" icon="gauge-high">
              Test and develop without worrying about accidentally exposing sensitive information
            </Card>

            <Card title="Audit-Ready" icon="clipboard-check">
              Demonstrate proper data handling practices with masked logs and interfaces
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <span>
          Security Enhancement
        </span>
      </div>
    </Card>

    ***

    ### **Performance improvements**

    <Card title="Performance improvements" icon="gauge-high">
      <Tabs>
        <Tab title="Caching Enhancements">
          FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Smart Caching" icon="database">
              Cache and reuse results automatically when identical input values are detected
            </Card>

            <Card title="Reduced Latency" icon="bolt">
              Start processes faster when repeating operations with the same parameters
            </Card>

            <Card title="Resource Optimization" icon="microchip">
              Reduce server load and improve resource utilization
            </Card>

            <Card title="Automatic Management" icon="wand-magic-sparkles">
              Manage cache automatically with no configuration required
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <Steps>
            <Step title="Response Times">
              Initialize processes faster in cached scenarios
            </Step>

            <Step title="Scalability">
              Handle more concurrent users with the same infrastructure
            </Step>

            <Step title="Cost Efficiency">
              Use fewer compute resources for high-volume scenarios
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <div>
        <span>
          Performance
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="Developer Experience">
    Enhanced tools and features for business rules development, testing, and workflow design.

    🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
    💾 [**REST API Response Caching**](#rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
    📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning--archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
    🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
    🧪 [**Business Rules Testing**](#business-rules-testing) - Save test parameters in reusable functions modal

    ### **Parallel branches in workflows**

    <Card title="Parallel branches in workflows" icon="code-branch">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.

          <Frame>
            <video />
          </Frame>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Start Parallel Node" icon="code-fork">
              Split workflow execution into multiple concurrent branches with start parallel nodes
            </Card>

            <Card title="End Parallel Node" icon="code-merge">
              Merge parallel branches with end parallel nodes that wait for all branches to complete
            </Card>

            <Card title="Path Visualization" icon="diagram-project">
              View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
            </Card>

            <Card title="Runtime Monitoring" icon="clock">
              Track parallel path execution with timing information for each branch and merge point
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Design Parallel Paths">
              Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
            </Step>

            <Step title="Configure Branch Logic">
              Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
            </Step>

            <Step title="Merge Paths">
              Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
            </Step>

            <Step title="Runtime Execution">
              All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
            </Step>
          </Steps>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Multiple API Calls" icon="cloud">
              Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
            </Card>

            <Card title="Data Enrichment" icon="database">
              Fetch data from multiple sources in parallel for comprehensive data aggregation
            </Card>

            <Card title="Notification Broadcasting" icon="bell">
              Send notifications through multiple channels (email, SMS, push) simultaneously
            </Card>

            <Card title="Document Processing" icon="file-lines">
              Process different document types or sections in parallel for faster throughput
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Runtime Behavior">
          <Accordion title="Path Timing">
            * **Path Time**: Sum of all node execution times within that branch
            * **End Parallel Time**: Node processing time + maximum time across all parallel paths
            * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
          </Accordion>

          <Accordion title="Console Logging">
            * **Start Parallel Node**: Displays Input tab showing data split across branches
            * **End Parallel Node**: Displays Output tab showing merged results from all branches
            * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
          </Accordion>

          <Accordion title="Error Handling">
            * If any branch fails, the workflow handles it according to standard error handling rules
            * End Parallel node waits for all non-failed branches before continuing
            * Runtime validation ensures parallel branches are configured correctly
          </Accordion>
        </Tab>

        <Tab title="Limitations">
          <Warning>
            **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
          </Warning>

          * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
          * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes

          <Info>
            Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
          </Info>
        </Tab>

        <Tab title="Benefits">
          <Steps>
            <Step title="Performance">
              Reduce workflow execution time by running independent operations concurrently instead of sequentially
            </Step>

            <Step title="Resource Utilization">
              Maximize throughput by executing multiple operations simultaneously
            </Step>

            <Step title="Design Clarity">
              Model concurrent operations explicitly in your workflow diagrams
            </Step>

            <Step title="Monitoring">
              Track execution time for each parallel path to identify bottlenecks
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <div>
        <span>
          Integration Designer
        </span>
      </div>
    </Card>

    ***

    ### **Integration Designer REST API response caching**

    <Card title="Integration Designer REST API response caching" icon="database">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
          </Frame>

          <Info>
            When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Flexible TTL Policies" icon="clock">
              Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
            </Card>

            <Card title="Cache Management" icon="broom">
              Clear cached responses from endpoint definitions or testing modals as needed
            </Card>

            <Card title="Cache Status Visibility" icon="eye">
              View cache status, keys, and TTL information in testing modals and workflow console logs
            </Card>

            <Card title="Automatic Fallback" icon="shield-check">
              System automatically calls the external API if cache retrieval fails, ensuring reliability
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="TTL Configuration">
          <Accordion title="Expires After (Duration-Based)">
            Cache responses for a specific duration after the request is made.

            **Configuration Options**:

            * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
            * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
            * **Default**: `R/P1D` (1 day)

            **Example**: Cache for 10 minutes after each request

            ```
            PT10M
            ```
          </Accordion>

          <Accordion title="Expires At (Time-Based)">
            Cache responses until a specific time of day with recurring patterns.

            **Configuration Options**:

            * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
            * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
            * **Time Unit**: Choose Day, Week, or Month (default: Day)

            **Example**: Cache until midnight every day

            ```
            Expire Time: 00:00
            Recurrency: 1
            Time Unit: Day
            ```

            **Example**: Cache until 6 PM every Friday

            ```
            Expire Time: 18:00
            Recurrency: 1
            Time Unit: Week
            ```
          </Accordion>
        </Tab>

        <Tab title="Cache Visibility">
          <Steps>
            <Step title="Testing Modal">
              View cache status directly in the endpoint testing modal with:

              * **Cache Hit/Miss Status**: Whether results came from cache
              * **Cache Key**: The unique identifier for the cached response
              * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
            </Step>

            <Step title="Workflow Console">
              Monitor cache usage in workflow execution logs with the same detailed information
            </Step>

            <Step title="Clear Cache Action">
              Clear cached responses from the endpoint page or testing modal when cache is configured
            </Step>
          </Steps>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Configure Caching">
              In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
            </Step>

            <Step title="First Request">
              When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
            </Step>

            <Step title="Subsequent Requests">
              If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
            </Step>

            <Step title="Cache Expiration">
              Once TTL expires, the next request fetches fresh data from the external API and updates the cache
            </Step>

            <Step title="Cache Management">
              Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
            </Step>
          </Steps>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Reference Data" icon="list">
              Cache country lists, product catalogs, or other reference data that rarely changes
            </Card>

            <Card title="Rate Limit Avoidance" icon="gauge-max">
              Reduce API calls to third-party services with strict rate limits
            </Card>

            <Card title="Cost Optimization" icon="coins">
              Lower operational costs by reducing billable API calls to external services
            </Card>

            <Card title="Performance" icon="bolt">
              Improve workflow execution speed by eliminating network latency for cached responses
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Error Handling">
          <Warning>
            **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
          </Warning>

          **Failure Scenarios**:

          * Cache service unavailable → Direct API call
          * Cache corruption or invalid data → Direct API call
          * Cache storage failure → Direct API call (with warning logged)

          Your workflows continue to function normally even if caching fails.
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Reduced API Costs" icon="dollar-sign">
              Minimize charges from external APIs by serving cached responses when data hasn't changed
            </Card>

            <Card title="Improved Performance" icon="rocket">
              Return responses instantly from cache instead of waiting for external API calls
            </Card>

            <Card title="Rate Limit Compliance" icon="scale-balanced">
              Stay within API rate limits by reducing the number of requests to external services
            </Card>

            <Card title="Better Scalability" icon="arrows-up-to-line">
              Handle higher workflow volumes without increasing external API calls
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <span>
          Integration Designer
        </span>
      </div>
    </Card>

    <Card title="REST Endpoint Caching" href="../../../5.1/docs/platform-deep-dive/integrations/integration-designer#rest-endpoint-caching" icon="book-open">
      Learn how to configure caching policies, manage cache, and optimize your REST API integrations
    </Card>

    ***

    ### **Workflow partitioning & archiving**

    <Card title="Workflow partitioning & archiving" icon="database">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.

          <Info>
            Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Time-Based Partitioning" icon="calendar">
              Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
            </Card>

            <Card title="Automatic Archiving" icon="box-archive">
              Automatically archive partitions older than the specified retention period to optimize active database size
            </Card>

            <Card title="Flexible Retention Policies" icon="clock">
              Configure how many time intervals to retain before archiving with granular control
            </Card>

            <Card title="Scheduled Archiving" icon="calendar-check">
              Use cron expressions to schedule archiving operations at optimal times
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          Configure workflow partitioning using environment variables in Integration Designer:

          <Accordion title="Partitioning Settings">
            * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
              * Default: `false`
              * Options: `true`, `false`

            * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
              * Default: `MONTH`
              * Options: `DAY`, `WEEK`, `MONTH`
          </Accordion>

          <Accordion title="Archiving Settings">
            * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
              * Default: `false`
              * Options: `true`, `false`

            * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
              * Default: `3`
              * Options: Any positive integer
              * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived

            * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
              * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
              * Options: Any valid cron expression
          </Accordion>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Enable Partitioning">
              Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
            </Step>

            <Step title="Configure Partition Interval">
              Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
            </Step>

            <Step title="Set Retention Policy">
              Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
            </Step>

            <Step title="Enable and Schedule Archiving">
              Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
            </Step>

            <Step title="Monitor Performance">
              Track database performance improvements as old partitions are archived and active data size is optimized
            </Step>
          </Steps>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="High-Volume Workflows" icon="gauge-high">
              Maintain performance for Integration Designer workflows processing thousands of instances daily
            </Card>

            <Card title="Compliance Requirements" icon="scale-balanced">
              Archive historical workflow data while maintaining access to recent instances for operational needs
            </Card>

            <Card title="Database Optimization" icon="database">
              Keep active database size manageable by automatically moving old data to archive partitions
            </Card>

            <Card title="Long-Running Deployments" icon="clock">
              Prevent database bloat in production environments running for extended periods
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Best Practices">
          <Warning>
            **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:

            * Ensure sufficient database storage for partition management operations
            * Start with archiving disabled to verify partitioning works correctly
            * Test thoroughly in non-production environments before enabling in production
            * Monitor database performance during initial archiving operations
            * Choose partition intervals based on your workflow volume and retention requirements
          </Warning>

          **Recommended Approach**:

          1. Enable partitioning first without archiving
          2. Monitor partition creation and database performance
          3. After verifying stable operation, enable archiving
          4. Schedule archiving during low-traffic periods (e.g., overnight)
          5. Start with longer retention periods and adjust based on requirements
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Improved Performance" icon="bolt">
              Maintain fast query performance as workflow instance count grows over time
            </Card>

            <Card title="Efficient Storage" icon="hard-drive">
              Optimize database storage by archiving historical data while keeping recent data accessible
            </Card>

            <Card title="Automatic Management" icon="wand-magic-sparkles">
              Set retention policies once and let the system handle archiving automatically
            </Card>

            <Card title="Scalability" icon="arrow-up-right-dots">
              Support long-running production deployments with predictable database growth
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <span>
          Integration Designer
        </span>
      </div>
    </Card>

    <Card title="Integration Designer Setup" href="../../../5.1/setup-guides/integration-designer-setup#workflow-partitioning-configuration" icon="book-open">
      Learn how to configure workflow partitioning and archiving for Integration Designer
    </Card>

    ***

    ### **Python IDE enhancements**

    <Card title="Python IDE enhancements" icon="code">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Autocomplete" icon="wand-magic-sparkles">
              Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
            </Card>

            <Card title="IntelliSense" icon="lightbulb">
              Use context-aware code completion with parameter hints and documentation
            </Card>

            <Card title="Syntax Highlighting" icon="highlighter">
              Read code more easily with enhanced Python syntax highlighting
            </Card>

            <Card title="Error Detection" icon="triangle-exclamation">
              Detect syntax errors in real-time with helpful error messages
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <Steps>
            <Step title="Development Speed">
              Write business rules faster with intelligent code suggestions
            </Step>

            <Step title="Error Reduction">
              Catch syntax errors before deployment with real-time validation
            </Step>

            <Step title="API Discovery">
              Discover available APIs and methods through IntelliSense
            </Step>

            <Step title="Professional Experience">
              Use IDE-quality editing features directly in FlowX Designer
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <div>
        <span>
          Developer Tools
        </span>
      </div>
    </Card>

    ***

    ### **Functions testing**

    <Card title="Functions testing" icon="flask">
      <Tabs>
        <Tab title="Overview">
          Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.

          <Frame>
            <video />
          </Frame>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Save Test Parameters" icon="floppy-disk">
              Save test inputs directly from the testing modal and reuse them in future test runs
            </Card>

            <Card title="Test History" icon="clock-rotate-left">
              Access previously saved test parameters for regression testing
            </Card>

            <Card title="Faster Iteration" icon="forward">
              Re-test functions quickly with saved parameter sets
            </Card>

            <Card title="Test Coverage" icon="check-double">
              Build a library of test cases for comprehensive function validation
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <Steps>
            <Step title="Quality">
              Test functions more thoroughly to improve quality
            </Step>

            <Step title="Time Savings">
              Avoid re-entering test data for each test iteration
            </Step>

            <Step title="Documentation">
              Use saved test cases as examples of how to use the function
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <div>
        <span>
          Testing Enhancement
        </span>
      </div>
    </Card>
  </Tab>

  <Tab title="Additional Improvements">
    Platform improvements, security updates, and bug fixes.

    🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
    🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
    🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements

    ### **Task management localization**

    <Card title="Task management localization" icon="language">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:

          <Frame>
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
          </Frame>

          * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
          * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Table Grid Localization (Automatic)" icon="table-columns">
              Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
            </Card>

            <Card title="Substitution Tags (Manual)" icon="tag">
              Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
            </Card>

            <Card title="Multi-language Support" icon="globe">
              Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
            </Card>

            <Card title="Task Action Localization" icon="list-check">
              Localize all task actions, statuses, and workflow-related text elements
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Localization components">
          <Accordion title="Table Grid Locale Keys">
            FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:

            * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
            * **Menus**: Column menus, context menus, aggregation functions, sorting options
            * **Pagination**: Page navigation, page size selectors, row counts
            * **Data Types**: Boolean values, dates, numbers with proper formatting
            * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
            * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies

            <Info>
              **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
            </Info>
          </Accordion>

          <Accordion title="FlowX substitution tags (51 keys)">
            Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:

            **Search & Navigation**

            * `sys_tm_search` - "Search"

            **Table Columns**

            * `sys_tm_title` - "Title"
            * `sys_tm_stage` - "Stage"
            * `sys_tm_assignee` - "Assignee"
            * `sys_tm_status` - "Status"
            * `sys_tm_priority` - "Priority"
            * `sys_tm_last_updated` - "Last updated"

            **Process States (Status Values)**

            * `sys_tm_created` - "Created"
            * `sys_tm_started` - "Started"
            * `sys_tm_finished` - "Finished"
            * `sys_tm_finished_with_error` - "Finished with error"
            * `sys_tm_failed` - "Failed"
            * `sys_tm_expired` - "Expired"
            * `sys_tm_aborted` - "Aborted"
            * `sys_tm_terminated` - "Terminated"
            * `sys_tm_dismissed` - "Dismissed"
            * `sys_tm_on_hold` - "On hold"

            **Bulk Actions**

            * `sys_tm_assign_to` - "Assign to…"
            * `sys_tm_unassign_all` - "Unassign All"
            * `sys_tm_assign_all_to_me` - "Assign All to me"
            * `sys_tm_hold_all` - "Hold All"
            * `sys_tm_unhold_all` - "Unhold All"

            **Task Actions**

            * `sys_tm_view_application` - "View Application"
            * `sys_tm_unassign` - "Unassign"
            * `sys_tm_assign_to_myself` - "Assign to myself"
            * `sys_tm_unhold` - "Unhold"
            * `sys_tm_hold` - "Hold"
            * `sys_tm_assign` - "Assign"
            * `sys_tm_execute` - "Execute"
            * `sys_tm_start` - "Start"

            **Task Details Sections**

            * `sys_tm_assignee_deactivated` - "(Deactivated)"
            * `sys_tm_comments` - "Comments"
            * `sys_tm_write_a_comment` - "Write a comment…"
            * `sys_tm_history` - "History"

            **History Events**

            * `sys_tm_task_created` - "Task created"
            * `sys_tm_user_created_this_task` - "`${user}` created this task"
            * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
            * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
            * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
            * `sys_tm_task_moved_to` - "Task moved to"
            * `sys_tm_task_status_changed_to` - "Task status changed to"
            * `sys_tm_task_assigned_to` - "Task assigned to"
            * `sys_tm_task_owner_removed` - "Task owner removed"

            **User Selection & Search**

            * `sys_tm_select_person` - "Select person..."
            * `sys_tm_search_person` - "Search users"
            * `sys_tm_search_term_validation` - "Type at least 4 characters..."

            **UI States**

            * `sys_tm_loading` - "Loading..."
            * `sys_tm_nothing_found` - "Nothing Found"

            **Data Display**

            * `sys_tm_in` - "In" (custom filter operator)
            * `sys_tm_yes` - "Yes" (boolean value)
            * `sys_tm_no` - "No" (boolean value)

            <Warning>
              **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
            </Warning>
          </Accordion>
        </Tab>

        <Tab title="Implementation">
          <Steps>
            <Step title="Set Container App Language">
              Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
            </Step>

            <Step title="Configure FlowX Substitution Tags in CMS">
              Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
            </Step>

            <Step title="Configure Custom Column Names (Optional)">
              If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
            </Step>

            <Step title="Test Localization">
              Verify complete localization:

              * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
              * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
            </Step>
          </Steps>

          <Info>
            **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
          </Info>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Global Reach" icon="earth-americas">
              Deploy Task Management to users worldwide with native language support
            </Card>

            <Card title="Consistent Experience" icon="check-double">
              Provide a fully localized experience across all Task Management components
            </Card>

            <Card title="Easy Maintenance" icon="wrench">
              Manage translations centrally through CMS substitution tags
            </Card>

            <Card title="Professional Quality" icon="award">
              Leverage professional translations for data grid components with automatic localization
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <div>
        <span>
          Localization
        </span>
      </div>
    </Card>

    <CardGroup>
      <Card title="Task Management Localization Guide" href="../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization" icon="book">
        Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
      </Card>

      <Card title="CMS Substitution Tags" href="../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags" icon="tags">
        Configure substitution tags in CMS for multi-language support
      </Card>

      <Card title="Task Management Overview" href="../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview" icon="list-check">
        Learn about Task Management features and configuration
      </Card>

      <Card title="Process Settings" href="../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager" icon="gear">
        Configure Task Management integration in process settings
      </Card>
    </CardGroup>

    ***

    ### **Platform enhancements**

    <Card title="Platform Enhancements" icon="server">
      FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.

      ## Security & Infrastructure Updates

      <CardGroup>
        <Card title="Vulnerability Fixes" icon="shield-virus">
          Update Java libraries and base images to address security vulnerabilities
        </Card>

        <Card title="SpiceDB Upgrade" icon="database">
          Upgrade SpiceDB with new operator version
        </Card>

        <Card title="Dependency Updates" icon="arrows-rotate">
          Update platform dependencies to latest secure versions
        </Card>
      </CardGroup>

      ## Additional improvements

      <CardGroup>
        <Card title="Permission-based UI" icon="user-lock">
          Add permission-based UI functionality in Reusable UI Templates
        </Card>

        <Card title="Database Query Improvements" icon="magnifying-glass">
          Improve FlowX Database query handling and error messages
        </Card>

        <Card title="System Substitution Tags" icon="tags">
          Use system substitution tags in task management texts in CMS
        </Card>

        <Card title="SSE Disconnect Handling" icon="plug">
          Handle Server-Sent Events disconnections better to reduce log noise
        </Card>

        <Card title="Integration Designer Environment Variables" icon="sliders" href="./update-environment-variables-5.2">
          Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
        </Card>
      </CardGroup>

      <div>
        <span>
          Platform Updates
        </span>
      </div>
    </Card>

    ***

    ### **Bug fixes**

    <Card title="Bug fixes & stability improvements" icon="wrench">
      FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.

      ## Notable fixes

      <Accordion title="Fixes">
        * **Process Instances Page**: Fix error when opening Runtime process instances page
        * **Resource Import**: Fix import requests that use incorrect content type
        * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
        * **Navigation Tree**: Fix navigation tree response for overridden processes
        * **Dependency Management**: Fix errors when updating library dependency versions
      </Accordion>

      <Accordion title="UI/UX fixes">
        * **Accessibility**: Fix missing accessibility sections on various components
        * **Theme Configuration**: Fix element selection issues in segmented button panel
        * **Modal Behavior**: Improve modal focus management and keyboard navigation
        * **Select Components**: Fix highlighting and navigation issues in select/multiselect
        * **Task Manager**: Fix browser freeze when opening table configuration
      </Accordion>

      <Accordion title="Renderer fixes">
        * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
        * **React SDK**: Fix option highlighting and keyboard navigation in various components
        * **Workflow Display**: Fix rendering issues in Integration Designer workflows
        * **Collection Components**: Fix card expansion issues with accordions in navigation areas
      </Accordion>

      <Accordion title="Backend fixes">
        * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
        * **Database Operations**: Improve error handling and validation for FlowX Database queries
        * **Process Navigation**: Fix back button redirects from process definitions
        * **Warning Management**: Clean up warnings properly when deleting parent actions
      </Accordion>
    </Card>
  </Tab>

  <Tab title="Info">
    ## Additional information

    ### Deployment information

    <Info>
      For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
    </Info>

    ### Environment variables updates

    <Info>
      For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
    </Info>

    ### Coming soon

    Additional features currently in development for future releases:

    * Extended accessibility support for iOS and Android platforms
    * Additional Python IDE capabilities
    * Enhanced FlowX Database query preview and optimization tools
  </Tab>
</Tabs>


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3



<Info>
  After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Component versions

| Component                  | 5.3.0       | 5.2.0   | 5.1.1   | 5.1.0   | 5.0.0  | 4.7.9   | 4.7.8  | 4.7.7  |
| -------------------------- | ----------- | ------- | ------- | ------- | ------ | ------- | ------ | ------ |
| **process-engine**         | **10.29.0** | 10.12.0 | 9.64.3  | 9.63.0  | 9.29.2 | 8.24.1  | 8.23.3 | 8.23.2 |
| **admin**                  | **10.26.1** | 10.12.0 | 9.66.5  | 9.65.0  | 9.25.2 | 7.18.4  | 7.17.3 | 7.16.3 |
| **designer**               | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core**               | **10.16.0** | 10.7.0  | 9.36.3  | 9.35.0  | 9.21.2 | 5.11.1  | 5.10.3 | 5.9.2  |
| **scheduler-core**         | **10.11.1** | 10.4.1  | 9.26.1  | 9.25.0  | 9.12.0 | 5.7.1   | 5.6.2  | 5.5.2  |
| **events-gateway**         | **10.12.1** | 10.4.1  | 9.26.1  | 9.25.0  | 9.12.0 | 5.7.1   | 5.6.2  | 5.5.2  |
| **notification-plugin**    | **10.17.0** | 10.7.0  | 9.29.1  | 9.28.0  | 9.14.2 | 6.8.1   | 6.7.2  | 6.6.2  |
| **document-plugin**        | **10.16.0** | 10.6.0  | 9.35.1  | 9.34.0  | 9.17.2 | 6.10.1  | 6.9.2  | 6.8.2  |
| **task-management-plugin** | **10.18.0** | 10.7.0  | 9.34.2  | 9.33.0  | 9.14.2 | 7.9.2   | 7.8.2  | 7.7.2  |
| **data-search**            | **10.10.1** | 10.4.1  | 9.23.1  | 9.22.0  | 9.12.1 | 4.7.1   | 4.6.2  | 4.5.2  |
| **audit-core**             | **10.15.1** | 10.6.0  | 9.30.1  | 9.29.1  | 9.15.2 | 6.8.1   | 6.7.2  | 6.6.2  |
| **advancing-controller**   | **10.11.0** | 10.4.1  | 9.25.1  | 9.24.0  | 9.11.0 | 4.7.1   | 4.6.2  | 4.6.2  |
| **integration-designer**   | **10.24.0** | 10.8.0  | 9.50.0  | 9.49.1  | 9.26.2 | 2.16.1  | 2.15.3 | 2.14.2 |
| **application-manager**    | **10.24.0** | 10.11.0 | 9.73.6  | 9.72.0  | 9.27.3 | 2.23.1  | 2.22.3 | 2.21.2 |
| **runtime-manager**        | **10.24.0** | 10.11.0 | 9.73.6  | 9.72.0  | 9.27.3 | 2.23.1  | 2.22.3 | 2.21.2 |
| **data-sync**              | **10.14.1** | 10.3.1  | 9.22.1  | 9.21.0  | 9.11.0 | 2.10.2  | 2.9.2  | 2.8.1  |
| **authorization-system**   | **10.18.1** | 10.7.0  | 9.34.2  | 9.33.0  | 9.14.2 | -       | -      | -      |
| **nosql-db-runner**        | **10.10.1** | 10.4.1  | 9.22.1  | 9.21.0  | 9.11.0 | -       | -      | -      |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component                     | 5.3.0       | 5.2.0   | 5.1.1   | 5.1.0   | 5.0.0  | 4.7.9   | 4.7.8  | 4.7.7  |
| ----------------------------- | ----------- | ------- | ------- | ------- | ------ | ------- | ------ | ------ |
| **@flowx/angular-sdk**        | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme**      | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk**          | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme**        | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit**   | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk**           | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme**         | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer**              | **10.1.0**  | 10.0.0  | 9.0.5   | 9.0.4   | 9.0.0  | 4.0.29  | 4.0.29 | 4.0.29 |
| **Android renderer**          | **10.1.0**  | 10.0.0  | 9.0.3   | 9.0.2   | 9.0.0  | 4.0.29  | 4.0.29 | 4.0.28 |

### Plugins

| Component            | 5.3.0  | 5.2.0  | 5.1.1  | 5.1.0  | 5.0.0  | 4.7.9  | 4.7.8  | 4.7.7  |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.0  | 0.2.0  | 0.2.0  | 0.2.0  |

### AI Platform

| Component                       | 5.3.0      | 5.2.0  | 5.1.1 | 5.1.0 | 5.0.0  | 4.7.9  | 4.7.8  | 4.7.7  |
| ------------------------------- | ---------- | ------ | ----- | ----- | ------ | ------ | ------ | ------ |
| **ai-assistant**                | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3  | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform**                 | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6  | 1.4.6  | 1.4.5  |
| **ai-platform-ai-developer**    | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-agents**          | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-conversations**   | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-models**          | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-tenants**         | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-planner**         | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-ai-analyst**      | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-ai-designer**     | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-agent-builder**   | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |
| **ai-platform-binaries**        | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  | -      | -      | -      |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.3.0            | Keycloak             | 26+                |
| 5.3.0            | Kafka                | 3.8 - 3.9          |
| 5.3.0            | PostgreSQL           | 16 - 17            |
| 5.3.0            | Oracle Database      | 21c, 23ai          |
| 5.3.0            | MongoDB              | 7 - 8              |
| 5.3.0            | Redis                | 7.4 - 8.0          |
| 5.3.0            | Elasticsearch        | 8                  |
| 5.3.0            | Angular (Web SDK)    | 19.2               |
| 5.3.0            | React (Web SDK)      | 18.x               |

<Warning>
  Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:

  * Keycloak versions older than 26
  * Kafka versions older than 3.8
  * Redis versions older than 7.4
</Warning>

## New in v5.3.0

### Key features and updates

<CardGroup>
  <Card title="UI Flows" icon="diagram-project">
    Build multi-platform applications with reusable UI components across web, iOS, and Android
  </Card>

  <Card title="UI Events" icon="bolt">
    Real-time user interaction handling with event-driven UI components
  </Card>

  <Card title="Workflow Data Models" icon="database">
    Workflow-level data models with input/output parameters and process-to-workflow data mapping
  </Card>

  <Card title="Mobile Accessibility" icon="universal-access">
    WCAG 2.1 accessibility compliance extended to iOS and Android platforms
  </Card>

  <Card title="Custom Component Enhancements" icon="puzzle-piece">
    Standardized custom component integration across all platforms
  </Card>

  <Card title="SaaS Capabilities" icon="building">
    Multi-tenant SaaS capabilities with organization management
  </Card>
</CardGroup>

## Upgrading from v5.2.0

### Breaking changes

<Warning>
  **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.
</Warning>

<Card title="Complete migration guide" href="./migrating-from-v5.2-to-v5.3/migration-overview" icon="map">
  See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting
</Card>

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

<Info>
  For detailed information on environment variable changes, see the [Update environment variables](./update-environment-variables-5.3) section.
</Info>

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

<Info>
  For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.
</Info>

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

<Info>
  FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.
</Info>

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

<Warning>
  This breaking change **only affects** deployments that have:

  * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
  * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)

  If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.
</Warning>

## Migration process

<Steps>
  <Step title="Review configuration changes">
    Understand the new configuration structure and identify which settings need to be updated in your deployment
  </Step>

  <Step title="Update configuration files">
    Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps
  </Step>

  <Step title="Deploy and verify">
    Deploy the updated configuration and verify that partitioning and archiving continue to work correctly
  </Step>
</Steps>

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable                                             | New Variable                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------ |
| `SCHEDULER_DATAPARTITIONING_ENABLED`                     | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`                        |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION`              | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`                 |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS`            | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`             |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE`          | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE`          |

## Backward compatibility

<Warning>
  **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.

  You must update your configuration before or immediately after upgrading to v5.3.0.
</Warning>

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

<Info>
  Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.
</Info>

<Info>
  This is a configuration-only change. No code changes, data migration, or schema updates are required.
</Info>

## Next steps

## Additional resources

<CardGroup>
  <Card title="Partitioning & Archiving Setup" href="/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving" icon="book">
    Complete guide to FlowX Engine partitioning and archiving
  </Card>

  <Card title="Deployment Guidelines v5.3.0" href="../deployment-guidelines-v5.3" icon="rocket">
    Component versions and deployment instructions
  </Card>

  <Card title="Release Notes v5.3.0" href="../v5.3.0-december-2025" icon="file-lines">
    Full release notes for v5.3.0
  </Card>
</CardGroup>

## Support

<Info>
  For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.
</Info>


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

<Note>
  FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.
</Note>

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable                        | Reason                                                         |
| ------------------------------------------- | -------------------------------------------------------------- |
| `SCHEDULER_DATAPARTITIONING_ENABLED`        | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`        |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name                                        | New Variable Name                                                  | Default Value | Description                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------- |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS`            | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`             | `3`           | Number of partition intervals to retain before archiving                            |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF`         | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE`          | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE`          | `5000`        | Batch size for moving data during archiving (PostgreSQL only)                       |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable                                                           | Default Value | Description                                                              |
| ------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------ |
| `FLOWX_DATA_PARTITIONING_ENABLED`                                  | `false`       | Turn on or off data partitioning                                         |
| `FLOWX_DATA_PARTITIONING_INTERVAL`                                 | `MONTH`       | Partition interval: `DAY`, `WEEK`, `MONTH`                               |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`                        | `false`       | Turn on or off automatic archiving of old partitions                     |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`             | `3`           | Number of intervals to retain before archiving                           |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`                 | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF`         | Compression for archived partitions (Oracle only)                        |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE`          | `5000`        | Batch size for data movement (PostgreSQL only)                           |

<Info>
  **Configuration structure changes:**

  * **Removed**: `scheduler.dataPartitioning` section
  * **Added**: `partitioning.archiving` subsection with all archiving-related settings
  * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
  * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`
</Info>

<Warning>
  **Action required if using partitioning:**

  If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:

  1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](./deployment-guidelines-v5.3#breaking-changes))
  2. **Environment variables**: Update variable names as shown in the tables above
  3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0
</Warning>

#### Configuration examples

<Tabs>
  <Tab title="Environment Variables (Before)">
    ```bash theme={"system"}
    # Old structure (v5.2 and earlier)
    SCHEDULER_DATAPARTITIONING_ENABLED=true
    SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
    FLOWX_DATA_PARTITIONING_ENABLED=true
    FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
    FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
    FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
    FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
    ```
  </Tab>

  <Tab title="Environment Variables (After)">
    ```bash theme={"system"}
    # New structure (v5.3.0)
    FLOWX_DATA_PARTITIONING_ENABLED=true
    FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
    FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
    FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
    FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
    FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
    FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
    ```
  </Tab>
</Tabs>

<Info>
  **Impact assessment:**

  This change only affects deployments that have:

  * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
  * Configured archiving settings

  If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.
</Info>

### New optional variables

| Variable                        | Default Value                                  | Description                                                                                                                           |
| ------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

<Info>
  The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.
</Info>

<Card title="Complete migration guide" href="migration-overview" icon="book">
  See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.
</Card>


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

<Tabs>
  <Tab title="App builder & reusability">
    Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.

    📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
    ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
    🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
    📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
    ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
    🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
    🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows

    ### **UI flows**

    <Card title="UI flows" icon="diagram-project">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.

          <Info>
            UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
          </Info>
        </Tab>

        <Tab title="Problem Solved">
          **Previous Limitations:**

          <CardGroup>
            <Card title="Unnecessary process complexity" icon="diagram-sankey">
              Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
            </Card>

            <Card title="Subprocess overhead" icon="layer-group">
              Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
            </Card>

            <Card title="Tight UI-process coupling" icon="link">
              UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
            </Card>

            <Card title="Platform-specific development" icon="code">
              Building the same UI for multiple platforms required separate implementations for each platform
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="UI Flows as project resources" icon="folder-tree">
              UI Flows are managed as independent project resources, separate from process definitions
            </Card>

            <Card title="Navigation areas management" icon="map">
              Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
            </Card>

            <Card title="Start process UI action" icon="play">
              Launch FlowX processes directly from UI Flows, bridging UI and process execution
            </Card>

            <Card title="Navigate to UI action" icon="arrow-pointer">
              Setup navigation to Nav areas or Container elements through scroll for seamless UX
            </Card>

            <Card title="Task Manager component" icon="list-check">
              Embed Task Manager as a UI Component in UI Flows for task management capabilities
            </Card>

            <Card title="Multi-platform support" icon="mobile">
              Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
            </Card>

            <Card title="Import/export" icon="file-export">
              Export UI Flows as portable packages and import them across environments and applications
            </Card>

            <Card title="Platform selection" icon="sliders">
              Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
            </Card>

            <Card title="Home page support" icon="home">
              Create UI Flows with dedicated home pages and home navigation icons for better UX
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Create UI flow">
              Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
            </Step>

            <Step title="Design navigation">
              Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
            </Step>

            <Step title="Add components">
              Add UI components including Task Manager, forms, custom components, and other UI elements
            </Step>

            <Step title="Configure actions">
              Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
            </Step>

            <Step title="Configure platforms">
              Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
            </Step>

            <Step title="Set home page">
              Designate a page as the home page with automatic home icon navigation support
            </Step>

            <Step title="Export & reuse">
              Export your UI Flow and import it into other applications or environments for maximum reusability
            </Step>
          </Steps>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Reduced complexity" icon="wand-magic-sparkles">
              Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
            </Card>

            <Card title="Faster development" icon="rocket">
              Build UI once instead of creating separate interfaces for each platform
            </Card>

            <Card title="Flexible architecture" icon="diagram-project">
              Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
            </Card>

            <Card title="Consistent UX" icon="check-double">
              Ensure identical user experiences across web, iOS, and Android applications
            </Card>

            <Card title="Reusability" icon="recycle">
              Share UI Flows across multiple applications and projects
            </Card>

            <Card title="Process integration" icon="gears">
              Launch processes from UI Flows when needed, maintaining clean separation of concerns
            </Card>

            <Card title="Maintainability" icon="wrench">
              Update UI in one place and propagate changes across all platforms
            </Card>

            <Card title="Enhanced navigation" icon="route">
              Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          **When to Use UI Flows vs Processes:**

          **Use UI Flows for:**

          * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
          * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
          * **Navigation Shells**: Application navigation structures and home pages
          * **Form Collections**: Data entry forms that start processes but don't need their own process context
          * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms

          **Use Processes for:**

          * **Business Logic**: Complex workflows with business rules, approvals, and integrations
          * **State Management**: Applications requiring process state tracking and persistence
          * **Orchestration**: Multi-step operations with decision points and parallel execution

          **Combine Both:**

          Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
        </Tab>
      </Tabs>

      <Card title="UI Flows Documentation" href="/5.9/docs/building-blocks/ui-flows" icon="book-open">
        Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
      </Card>

      <Badge icon="star">Major Feature</Badge>
    </Card>

    ***

    ### **UI events**

    <Card title="UI events" icon="bolt">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Event configuration" icon="gear">
              Configure UI Events in UI Designer with custom event types and handling logic
            </Card>

            <Card title="Cross-platform support" icon="globe">
              UI Events work consistently across Angular, React, iOS, and Android renderers
            </Card>

            <Card title="Runtime mapping" icon="diagram-project">
              UI Event results are mapped automatically in Reusable UI Template instances at runtime
            </Card>

            <Card title="Design-time testing" icon="flask">
              Test UI Events directly in UI Designer before deploying to runtime
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Form validation" icon="check-circle">
              Validate form inputs in real-time as users type, providing immediate feedback
            </Card>

            <Card title="Dynamic UI updates" icon="wand-magic-sparkles">
              Show/hide fields, update options, or change UI state based on user interactions
            </Card>

            <Card title="Client-side logic" icon="code">
              Execute lightweight client-side logic without triggering backend processes
            </Card>

            <Card title="Responsive interactions" icon="mouse-pointer">
              Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <Steps>
            <Step title="Performance">
              Handle UI interactions instantly without waiting for backend process execution
            </Step>

            <Step title="User experience">
              Provide immediate visual feedback and responsive interactions
            </Step>

            <Step title="Reduced complexity">
              Simplify process logic by handling UI-specific interactions at the component level
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UX Enhancement</Badge>
    </Card>

    ***

    ### **Custom component enhancements**

    <Card title="Custom component enhancements" icon="puzzle-piece">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Unified data mapping" icon="diagram-project">
              Standard data, saveData, and action body mapping across all platforms
            </Card>

            <Card title="Input key mapping" icon="key">
              Consistent input key handling for passing configuration and data to custom components
            </Card>

            <Card title="Platform parity" icon="equals">
              Identical custom component APIs across Angular, React, iOS, and Android
            </Card>

            <Card title="Action integration" icon="bolt">
              Integration with FlowX actions for triggering backend operations
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <Steps>
            <Step title="Developer productivity">
              Build custom components once with knowledge that applies across all platforms
            </Step>

            <Step title="Code reusability">
              Share component logic and patterns across web and mobile implementations
            </Step>

            <Step title="Consistency">
              Ensure consistent behavior and data handling across all platforms
            </Step>
          </Steps>
        </Tab>
      </Tabs>

      <Badge icon="code">Developer Experience</Badge>
    </Card>

    ***

    ### **File upload improvements**

    <Card title="File upload improvements" icon="file-arrow-up">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Enhanced loading behavior" icon="spinner">
              Configure loading behavior with optional overlay loader and custom loading messages
            </Card>

            <Card title="Toast notifications" icon="bell">
              Success and error messages displayed as toasts with customizable messages
            </Card>

            <Card title="Dynamic messages" icon="message">
              Display dynamic key values in toast and loading messages for context-aware feedback
            </Card>

            <Card title="Generic loader design" icon="palette">
              Updated loader designs across Angular, React, iOS, and Android for consistent theming
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Loading Behavior Options:**

          * **NONE**: No loading overlay displayed during upload
          * **OVERLAY**: Full-screen overlay with spinner and optional loading message

          **Toast Notifications:**

          * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
          * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
          * **Custom Messages**: Configure success and error messages with dynamic substitutions

          **Theming Support:**

          * Apply custom themes to loaders and toast messages
          * Configure colors, sizes, and styling to match your brand
          * Consistent visual language across platforms
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UX Enhancement</Badge>
    </Card>

    ***

    ### **Mobile accessibility**

    <Card title="Mobile accessibility" icon="universal-access">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="iOS accessibility" icon="mobile">
              Configure labels, hints, traits, and accessibility properties for iOS components
            </Card>

            <Card title="Android accessibility" icon="mobile-screen">
              Set content descriptions and accessibility properties for Android components
            </Card>

            <Card title="Designer integration" icon="sliders">
              Configure all accessibility properties from UI Designer without code changes
            </Card>

            <Card title="Platform-specific options" icon="gear">
              Set platform-specific accessibility configurations for optimal native experience
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Inclusive mobile apps" icon="users">
              Make your mobile applications accessible to users with disabilities
            </Card>

            <Card title="Regulatory compliance" icon="scale-balanced">
              Meet mobile accessibility requirements for government, healthcare, and financial sectors
            </Card>

            <Card title="Better UX" icon="star">
              Accessibility improvements benefit all users, not just those using assistive technologies
            </Card>

            <Card title="Unified configuration" icon="wrench">
              Configure accessibility for all platforms from a single Designer interface
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="universal-access">Accessibility</Badge>
    </Card>

    ***

    ### **Cross workspace projects**

    <Card title="Cross workspace projects" icon="layer-group">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.

          <Info>
            A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
          </Info>
        </Tab>

        <Tab title="Problem Solved">
          **Previous Limitations:**

          <CardGroup>
            <Card title="Environment testing restrictions" icon="ban">
              Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
            </Card>

            <Card title="Operational costs">
              This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Solution">
          **What Changed:**

          <Steps>
            <Step title="Restriction removed">
              The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
            </Step>

            <Step title="Independent lifecycles">
              Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
            </Step>

            <Step title="Workspace isolation">
              Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
            </Step>
          </Steps>
        </Tab>

        <Tab title="How It Works">
          **Import Behavior:**

          | Aspect                    | Behavior                                                                                                                |
          | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
          | **Import**                | Import a project build (and optionally a version) into a different workspace on the same environment                    |
          | **Active Policy**         | The imported build is automatically set as the active policy, regardless of what was active in the original workspace   |
          | **User Access**           | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
          | **Process Instances**     | Workspace-specific; imported projects start with no instances until processes run in the new workspace                  |
          | **Database**              | Projects across workspaces on the same environment share the same database                                              |
          | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances                     |

          <Warning>
            Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
          </Warning>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Flexible testing environments" icon="flask">
              Use workspaces to represent UAT, Staging, and other test environments on the same deployment
            </Card>

            <Card title="Reduced costs" icon="piggy-bank">
              Eliminate the need for additional deployments and DevOps resources for environment management
            </Card>

            <Card title="Better organization" icon="sitemap">
              Organize projects and environments more efficiently with workspace-based separation
            </Card>

            <Card title="Independent control" icon="sliders">
              Maintain separate policies and configurations for each workspace while using the same project
            </Card>

            <Card title="Simplified operations" icon="gears">
              Streamline deployment and environment management workflows
            </Card>

            <Card title="Faster environment setup" icon="bolt">
              Quickly create new test environments by importing existing projects into new workspaces
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          **Example Scenarios:**

          1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations

          2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project

          3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team

          4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
        </Tab>
      </Tabs>

      <Card title="Workspaces Documentation" href="/5.1/docs/projects/workspaces#cross-workspace-project-import" icon="book-open">
        Complete guide to cross-workspace project import, including import behavior and best practices.
      </Card>

      <Badge icon="recycle">Reusability Enhancement</Badge>
    </Card>

    ***

    ### **Collection and table actions**

    <Card title="Collection and table actions" icon="table-list">
      FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.

      <CardGroup>
        <Card title="Row-level actions" icon="hand-pointer">
          Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
        </Card>

        <Card title="Cross-platform support" icon="globe">
          Works in both Angular and React web renderers for UI Flows
        </Card>
      </CardGroup>

      <Badge icon="diagram-project">UI Flows</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Integration & data">
    Enhanced workflow integration, data model management, and backend performance improvements.

    🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
    🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
    🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
    🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
    📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
    🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
    🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
    🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
    ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
    🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements

    ### **Data mappers for workflow integration**

    <Card title="Data mappers for workflow integration" icon="diagram-project">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.

          <Frame title="Workflow Data Model">
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
          </Frame>

          <Frame title="Process to Workflow Mapping">
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
          </Frame>

          <Info>
            Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Workflow data model" icon="database">
              Define data models at the workflow level with input and output parameters, similar to Process Definitions
            </Card>

            <Card title="Input parameter management" icon="arrow-down-to-line">
              Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
            </Card>

            <Card title="Data parameters" icon="layer-group">
              Use data parameters to define input and output data subsets for workflow operations
            </Card>

            <Card title="Process ↔ workflow mapping" icon="arrows-left-right">
              Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
            </Card>

            <Card title="Generic CRUD endpoints" icon="code">
              Manage data models, entities, attributes, and data parameters programmatically via REST APIs
            </Card>

            <Card title="Unique node validation" icon="shield-check">
              Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Define workflow data model">
              Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
            </Step>

            <Step title="Configure input parameters">
              Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
            </Step>

            <Step title="Map process to workflow">
              When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
            </Step>

            <Step title="Map workflow to process">
              Configure output mappings on nodes to receive workflow results and map them back to process data
            </Step>
          </Steps>
        </Tab>

        <Tab title="Data Model Management">
          **New API Capabilities:**

          * **Data Model CRUD**: Create, read, update, and delete workflow data models
          * **Entity Management**: Add, modify, and remove entities within data models
          * **Attribute Management**: Define and manage attributes with types and validation rules
          * **Data Parameters Operations**: Create input and output data parameters for workflows
          * **Usage Tracking**: Query references and usages for attributes and entities
          * **Import/Export**: Export and import complete data models across environments

          **Technical Implementation:**

          * Centralized data model library for common classes and interfaces
          * Generic endpoints for data model and data parameters manipulation
          * Integration Designer communicates with Admin service for data model operations
          * Automatic input body computation based on data model input parameters
          * Runtime workflow start data endpoint for testing and execution
        </Tab>

        <Tab title="Limitations & Compatibility">
          **Current Limitations:**

          * **Start Subworkflow Node**: Works as-is without data model integration in this release
          * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
          * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)

          **Backwards Compatibility:**

          * Existing workflows continue to work without changes
          * End nodes from existing workflows can be renamed manually to align with output parameters
          * No breaking changes to current workflow execution

          **Node Naming:**

          * Node names must be unique within a workflow definition
          * System automatically validates uniqueness when renaming nodes
          * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Consistent data lineage" icon="timeline">
              Ensure data consistency across processes and workflows with structured data models
            </Card>

            <Card title="Simplified configuration" icon="wand-magic-sparkles">
              Input parameters automatically pre-fill Start Nodes - no manual JSON editing
            </Card>

            <Card title="Type safety" icon="shield-check">
              Define data types and validation rules at the workflow level for runtime safety
            </Card>

            <Card title="Reusability" icon="recycle">
              Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
            </Card>

            <Card title="Better testing" icon="flask">
              Test workflows with structured input data based on the data model
            </Card>

            <Card title="Clear interfaces" icon="sitemap">
              Workflow data models document the expected inputs and outputs for each workflow
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Card title="Workflow Data Models Documentation" href="/5.9/docs/platform-deep-dive/integrations/workflow-data-models" icon="book-open">
        Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
      </Card>

      <Badge icon="diagram-project">Integration Designer</Badge>
    </Card>

    ***

    ### **Workflow data model**

    <Card title="Workflow data model" icon="database">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="CRUD endpoints" icon="code">
              Create, read, update, and delete workflow data models programmatically via REST APIs
            </Card>

            <Card title="Data model paths" icon="route">
              Runtime endpoint for retrieving workflow data model paths and structure information
            </Card>

            <Card title="RUT instance mappings" icon="sitemap">
              Enhanced /status and /details endpoints with mappings per workflow instance
            </Card>

            <Card title="Runtime caching" icon="bolt">
              Improved caching for reusable templates to reduce latency and improve performance
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Dynamic forms" icon="form">
              Build dynamic forms based on data model structure at runtime
            </Card>

            <Card title="Data migration" icon="database">
              Automate data model synchronization across environments
            </Card>

            <Card title="Documentation" icon="book">
              Generate data model documentation automatically from API responses
            </Card>

            <Card title="Validation" icon="check-circle">
              Implement runtime validation based on data model definitions
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="code">API Enhancement</Badge>
    </Card>

    ***

    ### **MCP integration**

    <Card title="MCP integration" icon="robot">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.

          <Info>
            MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="MCP data sources" icon="plug">
              Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
            </Card>

            <Card title="Tool management" icon="wrench">
              View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
            </Card>

            <Card title="Custom agent integration" icon="robot">
              Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
            </Card>

            <Card title="Authentication support" icon="shield-check">
              Support for no authentication and OAuth 2.0 service account authentication methods
            </Card>

            <Card title="Tool discovery" icon="magnifying-glass">
              Automatic tool discovery from MCP servers with schema information for inputs and outputs
            </Card>

            <Card title="Execution monitoring" icon="chart-line">
              Track tool usage and execution details in console logs for debugging and monitoring
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Add MCP server">
              Configure an MCP server as a data source in Integration Designer with base URL and authentication details
            </Step>

            <Step title="Authenticate connection">
              Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
            </Step>

            <Step title="Discover tools">
              View available tools exposed by the MCP server with their input/output schemas
            </Step>

            <Step title="Enable tools">
              Enable or turn off specific tools based on your workflow requirements
            </Step>

            <Step title="Configure custom agent">
              Add a Custom Agent node to your workflow and select which MCP servers the agent can access
            </Step>

            <Step title="Execute workflow">
              AI agents can now use MCP tools during workflow execution to interact with external systems
            </Step>

            <Step title="Monitor execution">
              View tool usage and execution details in console logs for debugging and performance tracking
            </Step>
          </Steps>
        </Tab>

        <Tab title="Authentication">
          **Supported Authentication Methods:**

          **None**

          * No authentication required
          * Use for public MCP servers or development environments
          * Quick setup for testing and prototyping

          **Service Account (OAuth 2.0)**

          * OAuth 2.0 service account authentication
          * Required configuration:
            * **Client ID**: OAuth client identifier
            * **Client Secret**: OAuth client secret
            * **Identity Provider URL**: Authorization server endpoint
          * Use for production environments
          * Secure access to MCP servers
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="External API integration" icon="globe">
              Connect AI agents to external APIs and services for data retrieval and action execution
            </Card>

            <Card title="Database operations" icon="database">
              Query databases and perform data operations through MCP tools within AI workflows
            </Card>

            <Card title="Custom business logic" icon="code">
              Expose custom business logic as MCP tools for AI agents to execute
            </Card>

            <Card title="Multi-system orchestration" icon="sitemap">
              Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Standardized integration" icon="plug">
              Use a standardized protocol for AI agent tool integration across different systems
            </Card>

            <Card title="Extended capabilities" icon="wand-magic-sparkles">
              Extend AI agent capabilities with external tools without custom code
            </Card>

            <Card title="Flexible tool management" icon="sliders">
              Enable or turn off specific tools per MCP server based on workflow needs
            </Card>

            <Card title="Secure connections" icon="shield-check">
              Support for OAuth 2.0 authentication ensures secure access to external services
            </Card>

            <Card title="Tool reusability" icon="recycle">
              Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
            </Card>

            <Card title="Monitoring & debugging" icon="bug">
              Console logs provide visibility into tool execution for troubleshooting and optimization
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Card title="MCP Integration Documentation" href="/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview" icon="book-open">
        Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
      </Card>

      <Badge icon="robot">AI Integration</Badge>
    </Card>

    ***

    ### **Custom Agent nodes**

    <Card title="Custom Agent nodes" icon="robot">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
        </Tab>
      </Tabs>

      <Card title="Custom Agent Node Documentation" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node" icon="book-open">
        Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
      </Card>

      <Badge icon="robot">AI Integration</Badge>
    </Card>

    ***

    ### **Knowledge base**

    <Card title="Knowledge base" icon="book">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.

          <Info>
            Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Document upload" icon="file-arrow-up">
              Upload PDF documents directly into Knowledge Bases for AI agent access
            </Card>

            <Card title="Workflow ingestion" icon="diagram-project">
              Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
            </Card>

            <Card title="Semantic search" icon="magnifying-glass">
              AI agents find relevant information using natural language queries with vector embeddings
            </Card>

            <Card title="Content sources" icon="folder-tree">
              Organize content across multiple sources within a Knowledge Base for better management
            </Card>

            <Card title="Relevance scoring" icon="star">
              Configure minimum relevance thresholds (0-100%) to control response quality
            </Card>

            <Card title="Testing capabilities" icon="flask">
              Test queries and operations in isolation before adding them to production workflows
            </Card>

            <Card title="Custom agent integration" icon="robot">
              Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
            </Card>

            <Card title="Content versioning" icon="clock-rotate-left">
              Append, replace, or delete content sources with full traceability and state management
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="How It Works">
          <Steps>
            <Step title="Create Knowledge Base">
              Add a new Knowledge Base data source in Integration Designer
            </Step>

            <Step title="Ingest content">
              Upload PDF documents or ingest data from workflows into content sources
            </Step>

            <Step title="Automatic chunking">
              Content is automatically split into chunks and indexed in the vector database
            </Step>

            <Step title="Configure Custom Agent">
              Enable Knowledge Base in Custom Agent nodes and configure query parameters
            </Step>

            <Step title="Query execution">
              AI agents query the Knowledge Base using semantic search and receive relevant chunks
            </Step>

            <Step title="Response generation">
              Agents use retrieved chunks as context to generate accurate, informed responses
            </Step>
          </Steps>
        </Tab>

        <Tab title="Workflow Operations">
          **Knowledge Base operations available in workflows:**

          | Operation   | Description                                                                  |
          | ----------- | ---------------------------------------------------------------------------- |
          | **Append**  | Add new content to an existing content source without removing existing data |
          | **Replace** | Delete all existing content and replace with new content                     |
          | **Delete**  | Remove all content from a content source                                     |

          **Configuration Options:**

          * **Knowledge Base**: Select from local project libraries or dependencies
          * **Content Source**: Use existing sources, create new ones, or use workflow variables
          * **Content**: Static text, workflow variables, or configuration parameters
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Product documentation assistant" icon="book-open">
              Create Knowledge Bases with product documentation for AI agents to answer customer questions
            </Card>

            <Card title="Policy compliance" icon="scale-balanced">
              Upload company policies so AI agents can reference them when processing requests
            </Card>

            <Card title="Dynamic knowledge updates" icon="rotate">
              Ingest data from external systems through workflows to keep AI knowledge current
            </Card>

            <Card title="Multi-source synthesis" icon="layer-group">
              Organize information across sources and let AI agents synthesize comprehensive answers
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Contextual AI responses" icon="brain">
              AI agents provide accurate responses based on your organization's actual documentation
            </Card>

            <Card title="Dynamic updates" icon="bolt">
              Keep AI knowledge current by ingesting data from workflows automatically
            </Card>

            <Card title="Quality control" icon="gauge-high">
              Relevance scoring ensures only high-quality, relevant information is used
            </Card>

            <Card title="Centralized management" icon="sitemap">
              Manage all AI knowledge sources from a single location in Integration Designer
            </Card>

            <Card title="No code integration" icon="wand-magic-sparkles">
              Configure Knowledge Base queries directly in Custom Agent nodes without code
            </Card>

            <Card title="Testable" icon="flask">
              Test queries and see relevance scores before deploying to production
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Limitations">
          **Current Limitations:**

          <Warning>
            * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
            * Custom metadata cannot be defined (only system metadata is available)
            * AI agents can only use one Knowledge Base per Custom Agent node
            * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
          </Warning>
        </Tab>
      </Tabs>

      <Card title="Knowledge Base Documentation" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview" icon="book-open">
        Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
      </Card>

      <Badge icon="robot">AI Integration</Badge>
    </Card>

    ***

    ### **Update process variables**

    <Card title="Update process variables" icon="pen-to-square">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.

          <Frame title="Update Process Variables">
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
          </Frame>

          <Frame title="Update Process Variables">
            ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
          </Frame>

          <Info>
            Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
          </Info>
        </Tab>

        <Tab title="Problem Solved">
          **Previous Limitations:**

          <CardGroup>
            <Card title="Limited correction tools" icon="toolbox">
              Operations teams had minimal tools to correct production issues at the process-instance level
            </Card>

            <Card title="Blocked instances" icon="ban">
              No way to unblock stuck process instances without backend intervention or process restarts
            </Card>

            <Card title="Data correction challenges" icon="exclamation-triangle">
              Incorrect process data required complex workarounds or manual database modifications
            </Card>

            <Card title="Operational delays" icon="clock">
              Production issues required developer intervention, increasing resolution time
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Editor" icon="code">
              Edit process variables in a JSON editor with syntax validation and formatting
            </Card>

            <Card title="Multiple entry points" icon="arrow-pointer">
              Access from Process Instances page contextual menu or Process Instance page secondary navigation
            </Card>

            <Card title="Dual view modes" icon="toggle-on">
              Switch between Tree View (existing) and JSON View for variable visualization and editing
            </Card>

            <Card title="Full CRUD operations" icon="pen-to-square">
              Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
            </Card>

            <Card title="JSON validation" icon="shield-check">
              Automatic JSON format validation before saving to ensure data integrity
            </Card>

            <Card title="Snapshot history" icon="camera">
              Previous process variables are saved in a new snapshot table before changes are applied
            </Card>

            <Card title="Auto-sync to Task Manager" icon="list-check">
              Updated variables automatically sync to Task Manager using existing mechanism
            </Card>

            <Card title="Elasticsearch integration" icon="magnifying-glass">
              Process variables configured for data search are automatically updated in Elasticsearch
            </Card>

            <Card title="Permission-based access" icon="user-lock">
              Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
            </Card>

            <Card title="Export functionality" icon="download">
              Export button available near the view dropdown for downloading process variables
            </Card>
          </CardGroup>

          **Iteration 2 - Enhanced Review:**

          <Card title="Compare feature" icon="code-compare">
            Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
          </Card>
        </Tab>

        <Tab title="How It Works">
          **Accessing the Feature:**

          You can access the edit functionality from two entry points:

          1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
          2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode

          **Editing Process Variables:**

          <Steps>
            <Step title="Select active instance">
              Choose an active process instance (Started or On Hold status) that requires variable modification
            </Step>

            <Step title="Switch to JSON view">
              In the Variables tab, switch from Tree View to JSON View using the view dropdown
            </Step>

            <Step title="Click edit">
              Click the Edit button (visible only if you have process\_variables\_edit permission)
            </Step>

            <Step title="Modify in editor">
              Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
            </Step>

            <Step title="Validate JSON">
              Ensure your JSON format is valid before saving - the editor will highlight syntax errors
            </Step>

            <Step title="Save changes">
              Click Save to apply changes - a snapshot of previous values is automatically created
            </Step>

            <Step title="Auto-sync">
              System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
            </Step>

            <Step title="Review audit log">
              Check the Audit Log tab to confirm the modification was recorded with all details
            </Step>
          </Steps>
        </Tab>

        <Tab title="Permissions & Security">
          **Permission Requirements:**

          * **New Permission**: `process_variables_edit` available at workspace level
          * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
          * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)

          **Access Control:**

          * Edit option in UI is only visible to users with `process_variables_edit` permission
          * Save functionality is restricted to users with the required permission
          * Unauthorized users can view process variables but cannot modify them

          **Audit Logging:**

          Every process variable modification creates an audit log entry with:

          * Workspace ID
          * Feature: Process variables
          * Section: Process Instance
          * Application UUID and name
          * Subject: Process variables
          * Event: Edit
          * Subject Identifier: Process instance UUID
          * Body: JSON with new version of process parameters

          Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
        </Tab>

        <Tab title="Data Synchronization">
          **What Gets Updated:**

          <CardGroup>
            <Card title="Task Manager" icon="check">
              Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
            </Card>

            <Card title="Elasticsearch" icon="check">
              Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
            </Card>

            <Card title="Process instance params" icon="check">
              Primary process instance parameters are updated immediately in the database
            </Card>

            <Card title="Snapshot table" icon="check">
              Previous values are saved in a new snapshot table before changes are applied
            </Card>
          </CardGroup>

          **What Does NOT Get Updated:**

          <CardGroup>
            <Card title="Process snapshots" icon="x">
              Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
            </Card>

            <Card title="Debug table" icon="x">
              Process instance debug records remain unchanged - preserves execution history
            </Card>

            <Card title="Existing audit logs" icon="x">
              Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
            </Card>

            <Card title="Subprocess variables" icon="x">
              Child subprocess variables are not automatically updated - parent changes don't cascade to children
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Important Considerations">
          **Limitations & Best Practices:**

          <Warning>
            **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
          </Warning>

          <Warning>
            **Back Navigation**: Process snapshots used for "Allow back to this action" with "Reset process data" are not updated. Users navigating back will see original values, not modified ones.
          </Warning>

          <Warning>
            **Integration Messages**: If a token is waiting for an integration message, the integration was called with original values. Modifying variables after integration calls does not re-trigger integrations.
          </Warning>

          **Best Practices:**

          * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
          * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
          * **Test in Lower Environments**: When possible, test variable modifications in staging before production
          * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
          * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
          * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Faster issue resolution" icon="gauge-high">
              Operations teams can resolve production issues immediately without developer intervention
            </Card>

            <Card title="Reduced downtime" icon="arrow-down">
              Unblock stuck instances quickly, minimizing impact on end users and business processes
            </Card>

            <Card title="Operational independence" icon="user-shield">
              Empower ops teams with self-service tools for process-instance management
            </Card>

            <Card title="Data consistency" icon="check-double">
              Automatic sync ensures Task Manager and Elasticsearch reflect updated values
            </Card>

            <Card title="Full traceability" icon="timeline">
              Snapshots and audit logs provide complete history of all modifications for compliance
            </Card>

            <Card title="Reduced risk" icon="shield">
              Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
            </Card>

            <Card title="Flexible editing" icon="code">
              The JSON editor provides powerful JSON editing capabilities with validation
            </Card>

            <Card title="Historical preservation" icon="archive">
              Original values preserved in snapshot table for rollback scenarios
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          **Common Scenarios:**

          **1. Correct User Input Errors**

          * Customer submitted incorrect data in a loan application (wrong income, invalid address)
          * Operations team edits the variables to correct the information
          * Process continues without requiring customer to restart the application

          **2. Unblock Stuck Process Instances**

          * Process is waiting for external data that will never arrive (integration timeout, external system down)
          * Ops team updates the variable to provide expected data or skip the condition
          * Instance is unblocked and continues execution

          **3. Fix Integration Data Issues**

          * External system returned incorrect or incomplete data
          * Operations team corrects process variables to match expected values
          * Process continues with accurate data without re-calling the integration

          **4. Emergency Data Updates**

          * Critical business information changed after process started (regulatory update, pricing change)
          * Ops team modifies variables to reflect current information
          * Process continues with updated data without restart

          **5. Add Missing Attributes**

          * Process needs additional data that wasn't collected at start
          * Operations team adds new attributes or objects to process variables
          * Process can now access the required information

          **6. Remove Invalid Data**

          * Process contains incorrect or test data that shouldn't be there
          * Ops team deletes the problematic attributes or objects
          * Process continues with clean, valid data only

          **7. Update Task Manager Keywords**

          * Task search keywords need updating based on corrected data
          * Variables are modified and automatically synced to Task Manager
          * Tasks become searchable with correct keywords

          **8. Fix Elasticsearch Search Data**

          * Process data indexed for search contains errors
          * Operations team corrects variables configured for data search
          * Elasticsearch automatically updates, ensuring accurate search results

          <Info>
            This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
          </Info>
        </Tab>
      </Tabs>

      <Card title="Update Process Variables Documentation" href="/5.9/docs/projects/runtime/active-process/update-process-variables" icon="book-open">
        Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
      </Card>

      <Badge icon="wrench">Operations Enhancement</Badge>
    </Card>

    ***

    ### **Token view improvements**

    <Card title="Token view improvements" icon="table-columns">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.

          <Info>
            These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Horizontal scrolling" icon="arrows-left-right">
              The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
            </Card>

            <Card title="Frozen columns" icon="grip-vertical">
              Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
            </Card>

            <Card title="Hierarchical nesting" icon="sitemap">
              Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
            </Card>

            <Card title="Auto-expanded rows" icon="chevron-down">
              All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
            </Card>

            <Card title="Dynamic indentation" icon="indent">
              Indentation dynamically adjusts based on nesting depth, visually representing token relationships
            </Card>

            <Card title="Context column" icon="layer-group">
              New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
            </Card>

            <Card title="Initiator node column" icon="play">
              New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
            </Card>

            <Card title="First executed node column" icon="location-dot">
              New First Executed Node column displays the first node executed after token generation
            </Card>

            <Card title="UUID copy functionality" icon="copy">
              Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
            </Card>

            <Card title="Color-coded status tags" icon="tags">
              Token Status column uses color-coded tags for quick visual identification of token lifecycle states
            </Card>

            <Card title="Tooltip support" icon="info">
              Long node names are truncated with tooltips showing full text on hover for better readability
            </Card>

            <Card title="Timezone-aware timestamps" icon="clock">
              Last Updated column displays full datetime in browser timezone for accurate local time representation
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Table Columns">
          The enhanced token view includes the following columns:

          | Column                  | Description                                             | Special Behavior                                                                                                                                                                                                                       |
          | ----------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
          | **Token UUID**          | Unique identifier of the token                          | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll)         |
          | **Context**             | Displays contextual data for token                      | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level)                                                                                             |
          | **Initiator Node**      | Shows the node name that generated the token            | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name                                                                                                   |
          | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
          | **Current Node**        | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess                              |
          | **Current Node Status** | Shows the current execution status                      | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column                                                                                                                            |
          | **Token Status**        | Indicates lifecycle state                               | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification                                                                                                             |
          | **Last Updated**        | Timestamp of latest token state change                  | Displays full datetime in browser timezone                                                                                                                                                                                             |
          | **Actions**             | Available actions for the token                         | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens                                                                              |
        </Tab>

        <Tab title="Nesting Behavior">
          **Token Hierarchy Display:**

          <Steps>
            <Step title="Parent-child relationships">
              Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
            </Step>

            <Step title="Default expansion">
              All token rows are expanded by default, showing the complete token hierarchy immediately
            </Step>

            <Step title="Dynamic indentation">
              Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
            </Step>

            <Step title="Visual hierarchy">
              The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
            </Step>
          </Steps>

          **Initiator Node Logic:**

          * **Parent tokens**: Display "-" in Initiator Node column
          * **Child tokens from parallel gateway**: Display the parallel gateway node name
          * **Child tokens from boundary event**: Display the boundary event node name
          * **Child tokens from back in steps**: Display appropriate initiator information
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Better visibility" icon="eye">
              Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
            </Card>

            <Card title="Clear hierarchy" icon="sitemap">
              Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
            </Card>

            <Card title="Context awareness" icon="layer-group">
              Context column provides immediate visibility into which subprocess a token is executing within
            </Card>

            <Card title="Execution tracking" icon="route">
              Initiator Node and First Executed Node columns help track token origin and execution path
            </Card>

            <Card title="Quick actions" icon="bolt">
              Frozen Actions column ensures retry and view actions are always accessible without scrolling
            </Card>

            <Card title="Easy UUID access" icon="copy">
              Quick copy functionality for full UUIDs without needing to view token details
            </Card>

            <Card title="Visual status identification" icon="tags">
              Color-coded status tags enable quick identification of token states at a glance
            </Card>

            <Card title="Improved readability" icon="book-open">
              Tooltips for truncated names and timezone-aware timestamps improve overall readability
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          **Common Scenarios:**

          **1. Parallel Gateway Debugging**

          * View all parallel branches simultaneously with clear parent-child relationships
          * Identify which branch each token belongs to through hierarchical nesting
          * Track execution progress across multiple parallel paths

          **2. Embedded Subprocess Analysis**

          * Context column immediately shows which subprocess tokens are executing within
          * Understand nested subprocess relationships through indentation
          * Track token flow across multiple subprocess levels

          **3. Boundary Event Monitoring**

          * Initiator Node column shows which boundary event triggered each token
          * First Executed Node shows the execution path started by boundary events
          * Monitor non-interrupting boundary event token execution

          **4. Process Instance Troubleshooting**

          * Frozen UUID column ensures token identification is always visible
          * Copy UUID functionality enables quick token reference in support tickets
          * Color-coded status tags help identify problematic tokens quickly

          **5. Multi-Level Process Analysis**

          * Hierarchical view supports complex processes with multiple nesting levels
          * Dynamic indentation adapts to any nesting depth
          * All tokens visible by default without manual expansion
        </Tab>
      </Tabs>

      <Card title="Token Documentation" href="/5.1/docs/building-blocks/token" icon="book-open">
        Complete guide to tokens, including token status values, current node status, and detailed token status view.
      </Card>

      <Badge icon="sparkles">UX Enhancement</Badge>
    </Card>

    ***

    ### **Access management enhancements**

    <Card title="Access management enhancements" icon="shield-check">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.

          <Info>
            These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
          </Info>
        </Tab>

        <Tab title="New Role">
          **workspace\_operations\_editor**

          A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.

          <CardGroup>
            <Card title="Operations management" icon="rotate">
              Full CRUD access for process instance operations including migration and move token functionality
            </Card>

            <Card title="Process variables" icon="code">
              Edit permission for process variables on active instances across the workspace
            </Card>

            <Card title="Process instances" icon="list">
              Read and edit access to all process instances in the workspace
            </Card>

            <Card title="Workspace user inheritance" icon="layer-group">
              Inherits all base permissions from workspace\_user role including project creation
            </Card>
          </CardGroup>

          **Role Constraints:**

          * Cannot be edited or deleted (predefined role)
          * Extends workspace\_user with operations-specific permissions
          * Does not include broader runtime capabilities (builds, policies, scheduled processes)

          **Use Cases:**

          * Support engineers managing process migrations
          * Operations teams handling token movements
          * Technical support staff editing process variables
        </Tab>

        <Tab title="New Permissions">
          **Workspace-Level Permissions:**

          | Permission                               | Description                                                           | Roles with Access                                                                                           |
          | ---------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
          | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor`                   |
          | **Operations** (Read/Create only)        | Create operations and view all operations                             | `workspace_user`                                                                                            |
          | **Process Variables** (Edit)             | Edit process variables on active instances                            | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
          | **Process Instances** (Edit)             | Edit process instance data                                            | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |

          **Project-Level Permissions:**

          | Permission                             | Description                               | Roles with Access                 |
          | -------------------------------------- | ----------------------------------------- | --------------------------------- |
          | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
          | **UI Flows** (Read only)               | View UI Flows definitions                 | `project_viewer`                  |
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Principle of least privilege" icon="shield-check">
              Grant only the permissions needed for specific operational tasks
            </Card>

            <Card title="Dedicated operations teams" icon="users">
              Enable operations teams to work independently without full admin access
            </Card>

            <Card title="Clear separation of concerns" icon="diagram-project">
              Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
            </Card>

            <Card title="Flexible role combinations" icon="puzzle-piece">
              Combine with other workspace roles for customized access patterns
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Card title="Access Management Documentation" href="/5.1/setup-guides/access-management/roles-permissions-matrix" icon="book-open">
        Complete permissions matrix and role specifications for all FlowX roles.
      </Card>

      <Badge icon="shield-check">Access Management</Badge>
    </Card>

    ***

    ### **Performance and stability**

    <Card title="Performance and stability" icon="gauge-high">
      FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.

      ## Backend optimizations

      <CardGroup>
        <Card title="Optimistic lock improvements" icon="lock">
          Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
        </Card>

        <Card title="Events gateway optimization" icon="bolt">
          Update Redis read mode to XREAD BLOCK for more efficient event streaming
        </Card>

        <Card title="Database performance" icon="database">
          Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
        </Card>

        <Card title="Template caching" icon="memory">
          Enhanced caching for reusable templates at runtime reduces latency and improves throughput
        </Card>
      </CardGroup>

      ## Infrastructure updates

      <CardGroup>
        <Card title="Connector Topic Pattern" icon="message">
          Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
        </Card>

        <Card title="SpiceDB backup" icon="file-shield">
          Documented backup and restore procedures for SpiceDB for disaster recovery
        </Card>

        <Card title="Observability" icon="chart-line">
          Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
        </Card>

        <Card title="Security updates" icon="shield-check">
          Fix HIGH vulnerabilities in Designer 5.1.x and main branch
        </Card>

        <Card title="Renderer improvements" icon="code">
          Enhanced Angular renderer with action form submit functionality and substitution tag support
        </Card>
      </CardGroup>

      <Badge icon="gear">Platform Updates</Badge>
    </Card>

    ***

    ### **Exclusive gateways**

    <Card title="Exclusive gateways" icon="code-branch">
      FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.

      <CardGroup>
        <Card title="Expression testing" icon="flask">
          Test gateway expressions directly from the configuration panel with real-time validation
        </Card>

        <Card title="Committed version testing" icon="check-circle">
          Test business rules and gateway expressions in committed versions
        </Card>

        <Card title="Code editor integration" icon="code">
          Enhanced code editor with syntax highlighting for complex expressions
        </Card>

        <Card title="Payload synchronization" icon="rotate">
          Test payloads automatically update when rules are saved
        </Card>
      </CardGroup>

      <Badge icon="code-branch">Process Logic</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Bug fixes & stability">
    Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.

    🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
    🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
    ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
    🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes

    ### **Designer fixes**

    <Card title="Designer fixes" icon="palette">
      FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.

      ## UI designer improvements

      <Accordion title="Configuration & styling">
        * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
        * **Fixed UI blocking** when slider min value exceeds max value
        * **Fixed warning icon display** in config panel
        * **Fixed expression test modal styles** when opened in resized screen
        * **Fixed UI action section refresh** when selecting different UI template
        * **Fixed UI action section rendering** after clicking 'Add new ui action'
      </Accordion>

      <Accordion title="File upload component">
        * **Fixed loading spinner toggle** not available for Overlay loading behavior
        * **Fixed incomplete loading behavior dropdown**
        * **Fixed default messages** not displayed after undo
        * **Fixed forms in collections handling** for patch actions requests
      </Accordion>

      <Accordion title="UI Flows designer">
        * **Fixed task management error state** when view is selected
        * **Fixed tab content preview** showing content from 2 tabs when adding new tab
      </Accordion>

      <Accordion title="Output parameters">
        * **Fixed currency key management** - can now add/remove currency key in output params
      </Accordion>

      <Accordion title="Exclusive Gateways">
        * **Fixed gateway decisions** can now be modified after initial save
        * **Fixed test payload** updates when rules are saved
        * **Fixed expression propagation** to test modal
      </Accordion>

      ## Frontend runtime fixes

      <Accordion title="Process management">
        * **Fixed context column** showing empty value for tokens in embedded subprocesses
        * **Fixed process params update** from running process instance modal
        * **Fixed long node names** overlapping adjacent columns in Tokens table
        * **Fixed workspace redirect** on page refresh
      </Accordion>

      <Accordion title="Audit & logging">
        * **Fixed audit log subject value** not displayed for process params updates
        * **Fixed toast error messages** to use text from backend request
        * **Added documentation link** to Modify Variables modal info text
      </Accordion>

      <Badge icon="palette">Designer Stability</Badge>
    </Card>

    ***

    ### **Renderer fixes**

    <Card title="Renderer fixes" icon="code">
      FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.

      ## Web renderers (Angular & React)

      <Accordion title="File upload component">
        * **Fixed theming** not applied to general loader
        * **Fixed theming** not applied to toast messages
        * **Fixed dynamic key values** not displayed in toast/loading messages
        * **Fixed success toast** displayed when flag is false
      </Accordion>

      <Accordion title="Card & navigation">
        * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
        * **Fixed card collapse** when next nav area is modal (Angular & React)
        * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
      </Accordion>

      <Accordion title="UI events">
        * **Fixed UI event triggering** without user interaction (Angular)
      </Accordion>

      <Accordion title="Call activity">
        * **Fixed call activity UT rendering** when started from embedded process
      </Accordion>

      <Accordion title="Collections & forms">
        * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
        * **Fixed multi-select search** filtering (React)
        * **Fixed JSON generation** with special characters in CollectionsV2
      </Accordion>

      ## Mobile renderers

      <Accordion title="Android">
        * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
      </Accordion>

      <Badge icon="code">Renderer Stability</Badge>
    </Card>

    ***

    ### **Backend fixes**

    <Card title="Backend fixes" icon="server">
      Backend stability and performance improvements across core services.

      ## Process management

      <Accordion title="Process & build issues">
        * **Fixed processes not displayed** in container app list for imported builds
        * **Fixed token state** changing from Aborted to Active during back navigation
        * **Fixed audit logs** for override operations after merge
      </Accordion>

      <Accordion title="Performance">
        * **Fixed /details endpoint** returning cache error for processes with many components
      </Accordion>

      <Accordion title="Process engine">
        * **Fixed token stuck** in receive node when message received after advancing
        * **Fixed action params** copied correctly for child actions when copying node
        * **Fixed metadata preservation** when importing process
      </Accordion>

      ## Security & configuration

      <Accordion title="Authentication">
        * **Fixed service account client secret** configuration parameter in Authorization service
      </Accordion>

      ## Data management

      <Accordion title="Runtime issues">
        * **Fixed FlowxProps.events** mapping at runtime for array of objects
      </Accordion>

      ## Infrastructure

      <Accordion title="Database & events">
        * **Fixed advancing errors** in partition event table
        * **Fixed Liquibase logging** when crashing due to lock
      </Accordion>

      <Badge icon="server">Backend Stability</Badge>
    </Card>

    ***

    ### **Data and integration fixes**

    <Card title="Data and integration fixes" icon="diagram-project">
      Fixes for data mappers and workflow integration features.

      ## Data mapper issues

      <Accordion title="Mapping operations">
        * **Fixed 400 error** when saving mappings
        * **Fixed error** when saving mapping with empty parameters
        * **Fixed unsaved mapping modal** displayed when saving action
        * **Fixed array mapping** - arrays in mapper functions now work correctly
        * **Fixed slice deletion** when updating PDM objects
      </Accordion>

      <Accordion title="Data streams & workflows">
        * **Fixed data stream availability** for older exports during import
        * **Fixed workflow data stream** data appending issue
        * **Fixed legacy mapping** toggle now triggers correctly for call activity
      </Accordion>

      <Accordion title="UI updates">
        * **Fixed start node** not updated in UI after parameters update until refresh
        * **Fixed manifest resource** not found after switching versions
      </Accordion>

      <Info>
        Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
      </Info>

      <Badge icon="diagram-project">Integration Stability</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    ### Deployment information

    <Info>
      For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
    </Info>

    ### Environment variable updates

    <Info>
      For detailed information on environment variable changes, see the [Update environment variables](./update-environment-variables-5.3) section.
    </Info>

    ### Breaking changes

    <Warning>
      **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
    </Warning>

    <Card title="Migration guide" href="./migrating-from-v5.2-to-v5.3/migration-overview" icon="map">
      Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
    </Card>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade path" icon="arrow-up-right-dots">
        Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
      </Card>

      <Card title="Component compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3
      </Card>
    </CardGroup>
  </Tab>
</Tabs>


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4



<Info>
  After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Component versions

| Component                  | 5.4.0       | 5.3.0   | 5.2.0   | 5.1.1   | 5.1.0   | 5.0.0  |
| -------------------------- | ----------- | ------- | ------- | ------- | ------- | ------ |
| **process-engine**         | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3  | 9.63.0  | 9.29.2 |
| **admin**                  | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5  | 9.65.0  | 9.25.2 |
| **designer**               | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core**               | **10.22.0** | 10.16.0 | 10.7.0  | 9.36.3  | 9.35.0  | 9.21.2 |
| **scheduler-core**         | **10.15.0** | 10.11.1 | 10.4.1  | 9.26.1  | 9.25.0  | 9.12.0 |
| **events-gateway**         | **10.17.0** | 10.12.1 | 10.4.1  | 9.26.1  | 9.25.0  | 9.12.0 |
| **notification-plugin**    | **10.22.0** | 10.17.0 | 10.7.0  | 9.29.1  | 9.28.0  | 9.14.2 |
| **document-plugin**        | **10.23.0** | 10.16.0 | 10.6.0  | 9.35.1  | 9.34.0  | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0  | 9.34.2  | 9.33.0  | 9.14.2 |
| **data-search**            | **10.14.0** | 10.10.1 | 10.4.1  | 9.23.1  | 9.22.0  | 9.12.1 |
| **audit-core**             | **10.21.0** | 10.15.1 | 10.6.0  | 9.30.1  | 9.29.1  | 9.15.2 |
| **advancing-controller**   | **10.16.0** | 10.11.0 | 10.4.1  | 9.25.1  | 9.24.0  | 9.11.0 |
| **integration-designer**   | **10.38.0** | 10.24.0 | 10.8.0  | 9.50.0  | 9.49.1  | 9.26.2 |
| **application-manager**    | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6  | 9.72.0  | 9.27.3 |
| **runtime-manager**        | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6  | 9.72.0  | 9.27.3 |
| **data-sync**              | **10.20.1** | 10.14.1 | 10.3.1  | 9.22.1  | 9.21.0  | 9.11.0 |
| **authorization-system**   | **10.28.0** | 10.18.1 | 10.7.0  | 9.34.2  | 9.33.0  | 9.14.2 |
| **nosql-db-runner**        | **10.17.0** | 10.10.1 | 10.4.1  | 9.22.1  | 9.21.0  | 9.11.0 |
| **email-gateway**          | **10.9.0**  | -       | -       | -       | -       | -      |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component                     | 5.4.0       | 5.3.0   | 5.2.0   | 5.1.1   | 5.1.0   | 5.0.0  |
| ----------------------------- | ----------- | ------- | ------- | ------- | ------- | ------ |
| **@flowx/angular-sdk**        | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme**      | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk**          | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme**        | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit**   | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk**           | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme**         | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer**              | **10.2.0**  | 10.1.0  | 10.0.0  | 9.0.5   | 9.0.4   | 9.0.0  |
| **Android renderer**          | **10.2.0**  | 10.1.0  | 10.0.0  | 9.0.3   | 9.0.2   | 9.0.0  |

### Plugins

| Component            | 5.4.0  | 5.3.0  | 5.2.0  | 5.1.1  | 5.1.0  | 5.0.0  |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.0  |

### AI Platform

| Component                       | 5.4.0      | 5.3.0  | 5.2.0  | 5.1.1 | 5.1.0 | 5.0.0  |
| ------------------------------- | ---------- | ------ | ------ | ----- | ----- | ------ |
| **ai-assistant**                | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3  |
| **di-platform**                 | 10.2.5     | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer**    | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-agents**          | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-conversations**   | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-models**          | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-tenants**         | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-planner**         | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-ai-analyst**      | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-ai-designer**     | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-agent-builder**   | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |
| **ai-platform-binaries**        | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1  |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.4.0            | Keycloak             | 26+                |
| 5.4.0            | Kafka                | 3.8 - 3.9          |
| 5.4.0            | PostgreSQL           | 16 - 17            |
| 5.4.0            | Oracle Database      | 21c, 23ai          |
| 5.4.0            | MongoDB              | 7 - 8              |
| 5.4.0            | Redis                | 7.4 - 8.0          |
| 5.4.0            | Elasticsearch        | 8                  |
| 5.4.0            | Angular (Web SDK)    | 20                 |
| 5.4.0            | React (Web SDK)      | 18.x               |

<Warning>
  Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:

  * Keycloak versions older than 26
  * Kafka versions older than 3.8
  * Redis versions older than 7.4
</Warning>

## New in v5.4.0

### Key features and updates

<CardGroup>
  <Card title="Email Trigger" icon="envelope">
    Start processes automatically from incoming emails with configurable validation rules
  </Card>

  <Card title="MCP Server Improvements" icon="server">
    Enhanced audit logging, resource management, and tool refresh capabilities
  </Card>

  <Card title="Email Gateway" icon="envelope-open-text">
    New microservice for handling email communication workflows
  </Card>
</CardGroup>

## Upgrading from v5.3.0

### Breaking changes

<Info>
  FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.
</Info>

### New environment variables

The following new environment variables have been introduced:

| Variable                         | Service        | Description                                                                                                           |
| -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set)               |
| `KAFKA_BOOTSTRAP_SERVERS`        | All services   | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible)  |
| `KAFKA_SECURITY_PROTOCOL`        | All services   | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

<Info>
  FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.
</Info>

The Email Gateway requires the following infrastructure:

| Component  | Requirement                                   |
| ---------- | --------------------------------------------- |
| PostgreSQL | Dedicated database named `email_gateway`      |
| MongoDB    | Connection to existing `app-runtime` database |
| Kafka      | Access to the FlowX Kafka cluster             |
| Redis      | Shared Redis instance                         |
| Keycloak   | Service account for authentication            |

<Note>
  The Email Gateway operates as an internal service and does not require ingress configuration.
</Note>

<Card title="Email Gateway Setup Guide" href="/5.1/setup-guides/email-gateway-setup" icon="envelope-open-text">
  Complete setup instructions including Helm values, environment variables, and troubleshooting.
</Card>

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

<Info>
  For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.
</Info>

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

<Info>
  FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.
</Info>

<Note>
  **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:

  * **Self-Managed** (On-Premises / Customer Cloud)
  * **FlowX SaaS** (FlowX-hosted)

  **Feature availability badges:**

  * <Badge icon="cloud">SaaS</Badge> Features exclusive to FlowX SaaS deployments
  * <Badge icon="building">Self-Managed</Badge> Features specific to self-managed deployments
  * <Badge icon="globe">All Deployments</Badge> Features available in both deployment models
</Note>

**What's new?**

<Tabs>
  <Tab title="SaaS & multi-tenancy">
    <Info>
      The features described in this section apply to **FlowX SaaS deployments**.\
      Self-managed deployments are not affected unless explicitly stated.
    </Info>

    FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.

    🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning

    ### **SaaS multi-tenancy**

    <Card title="SaaS multi-tenancy" icon="building">
      Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.

      <CardGroup>
        <Card title="Multi-tenant architecture" icon="building">
          Multiple organizations operate on shared infrastructure with complete isolation
        </Card>

        <Card title="Tenant isolation" icon="shield-check">
          Complete data and authentication isolation between organizations
        </Card>

        <Card title="Organization provisioning" icon="server">
          Automatic provisioning of dedicated resources for each organization
        </Card>

        <Card title="Resource management" icon="folder-tree">
          Each organization receives dedicated resources and project spaces
        </Card>
      </CardGroup>

      <Card title="Documentation" icon="book" href="/5.9/docs/saas/saas-overview">
        See the complete FlowX SaaS documentation for guides and best practices.
      </Card>

      <Badge icon="star">Major Feature</Badge>
      <Badge icon="cloud">SaaS</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="AI & Integration">
    Enhanced MCP server management.

    📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
    💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
    🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates

    ### **Email trigger**

    <Card title="Email trigger" icon="envelope-open-text">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.

          <Info>
            Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
          </Info>

          <Card title="Documentation" icon="book" href="/5.9/docs/platform-deep-dive/integrations/email-trigger">
            See the complete Email Trigger documentation for configuration guides and examples.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="IMAP Connection" icon="envelope">
              Connect to any IMAP-compatible email server with SSL/TLS support
            </Card>

            <Card title="Message Start Event" icon="play">
              New trigger type option in Message Start Event nodes to use Email Triggers
            </Card>

            <Card title="Attachment handling" icon="paperclip">
              Automatic upload of email attachments to Document Plugin with file validation
            </Card>

            <Card title="Validation rules" icon="filter">
              Configure allowed file types, maximum file size, and attachment count limits
            </Card>

            <Card title="Manage triggers" icon="list-check">
              Central Runtime page to activate, deactivate, and monitor email triggers
            </Card>

            <Card title="Failed triggers" icon="triangle-exclamation">
              Dedicated page to view and troubleshoot failed email processing attempts
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Data Source Settings:**

          | Field       | Description                       |
          | ----------- | --------------------------------- |
          | Protocol    | IMAP (currently supported)        |
          | Server Host | IMAP server hostname              |
          | Port        | Connection port (993 for SSL/TLS) |
          | Username    | Email account username            |
          | Password    | Email account password            |
          | SSL/TLS     | Enable secure connection          |

          **Filtering Criteria:**

          * **Email Address**: Monitored email address (read-only, based on authentication)
          * **Mailbox Folder**: Folder to monitor (default: Inbox)

          **Validation Options:**

          * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
          * **Maximum File Size**: Up to 25 MB per attachment
          * **Maximum File Count**: Limit attachments per email

          <Tip>
            All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
          </Tip>
        </Tab>

        <Tab title="Email Data Schema">
          When an email triggers a process, the following data structure is available:

          ```json theme={"system"}
          {
            "emailMessage": {
              "subject": "Support Request #12345",
              "dateTime": "2026-01-15T10:30:00Z",
              "sender": "customer@example.com",
              "body": "Email body content...",
              "fileAttachments": [{
                "filePath": "email-attachments/proc-123/file.pdf",
                "downloadPath": "/api/internal/files/uuid/download"
              }],
              "headerParams": {
                "Message-ID": "<abc123@example.com>"
              }
            }
          }
          ```
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Customer support automation" icon="headset">
              Automatically create support tickets from incoming customer emails
            </Card>

            <Card title="Document processing" icon="file-lines">
              Process attached documents through automated workflows
            </Card>

            <Card title="Request handling" icon="inbox">
              Route requests to appropriate departments based on email content
            </Card>

            <Card title="Notification processing" icon="bell">
              Process automated notifications from external systems
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="star">Major Feature</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Chat component**

    <Card title="Chat component" icon="comments">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.

          <Info>
            The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
          </Info>

          <Card title="Documentation" icon="book" href="/5.9/ai-platform/chat-component">
            See the complete Chat Component documentation for configuration guides and best practices.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Standalone chat tab" icon="message">
              Dedicated chat interface available as a standalone tab in web container apps
            </Card>

            <Card title="Message history" icon="clock-rotate-left">
              Persistent chat history with automatic scrolling to the latest messages
            </Card>

            <Card title="AI agent integration" icon="robot">
              Connect to workflows powered by AI agents
            </Card>

            <Card title="Session management" icon="id-badge">
              Automatic session handling with persistence across page refreshes
            </Card>

            <Card title="Customizable UI" icon="palette">
              Themeable components with comprehensive style configuration through Theme Admin
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Component setup:**

          * Add Chat component from UI Designer to your UI Flow
          * Select a workflow to handle chat interactions
          * Configure header, messages, and input properties
          * Apply custom styling through Theme Admin

          **Display modes:**

          * Full screen (v5.4.0)
          * Additional modes planned for v5.5
        </Tab>

        <Tab title="Improvements">
          **Session handling:**

          * Chat session ID is now generated when the first message is sent (not when opening the chat)
          * Improved session tracking

          **Message display:**

          * Latest messages are automatically scrolled into view after loading chat history
          * User input formatting (JSON, multiline text) is now preserved in displayed messages

          **Platform support:**

          * Available in both Angular and React web renderers
          * Mobile support planned for v5.5
        </Tab>
      </Tabs>

      <Badge icon="robot">AI Integration</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **MCP server improvements**

    <Card title="MCP server improvements" icon="server">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Audit logging" icon="clipboard-list">
              Complete audit trail for MCP server operations including creation, updates, and tool execution
            </Card>

            <Card title="Tool refresh" icon="rotate">
              Update MCP servers to fetch new tools without recreating the data source
            </Card>

            <Card title="Resource tracking" icon="chart-pie">
              Track MCP server usage across workflows with proper resource management
            </Card>

            <Card title="Copy support" icon="copy">
              Properly preserve MCP server selections when copying or duplicating workflows
            </Card>

            <Card title="SSE streaming" icon="stream">
              Fixed SSE event streaming to deliver events individually as they complete
            </Card>

            <Card title="Exception handling" icon="triangle-exclamation">
              Improved error handling and reporting for MCP server operations
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Bug Fixes">
          * **Tool updates**: Updating MCP servers now correctly fetches new tools
          * **Workflow copy**: MCP server selections are preserved when copying workflows
          * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
          * **SSE events**: Events are now streamed individually instead of all at once
          * **Audit entries**: Fixed missing event and subject in audit log entries
        </Tab>
      </Tabs>

      <Badge icon="robot">AI Integration</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Rendering">
    UI component enhancements and navigation improvements for web applications.

    🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
    🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
    📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
    📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements

    ### **Card default collapse state**

    <Card title="Card default collapse state" icon="square-caret-down">
      FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.

      <Tabs>
        <Tab title="Overview">
          When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.

          <Card title="Documentation" icon="book" href="/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card">
            See the complete Card component documentation for configuration details.
          </Card>
        </Tab>

        <Tab title="Configuration">
          **Default collapse state options:**

          | State         | Description                                                             |
          | ------------- | ----------------------------------------------------------------------- |
          | **Expanded**  | The card content is visible when the screen loads (default behavior)    |
          | **Collapsed** | The card content is hidden when the screen loads; users click to expand |

          <Info>
            This property is only available when the **Has accordion** setting is enabled on the Card component.
          </Info>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Progressive disclosure" icon="layer-group">
              Start with collapsed sections to reduce initial visual complexity
            </Card>

            <Card title="Optional content" icon="eye-slash">
              Hide less important information by default while keeping it accessible
            </Card>

            <Card title="Long forms" icon="rectangle-list">
              Break up lengthy forms into collapsible sections for better navigation
            </Card>

            <Card title="FAQ sections" icon="circle-question">
              Display questions collapsed with answers revealed on click
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **UI Flow Breadcrumbs**

    <Card title="UI Flow Breadcrumbs" icon="route">
      <Tabs>
        <Tab title="Overview">
          Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.

          <Info>
            Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
          </Info>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Navigation breadcrumbs UI component" icon="route">
              Display breadcrumbs UI component for UI Flows showing the current navigation path
            </Card>

            <Card title="Admin theme configuration" icon="palette">
              Configure breadcrumb appearance and styling through Admin theme settings
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Theme Configuration:**

          * Configure breadcrumb styling through Admin theme settings
          * Customize colors, fonts, and spacing to match your application design
          * Apply consistent styling across all UI Flows
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **UI Flow Sessions**

    <Card title="UI Flow Sessions" icon="window-restore">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.

          <Info>
            UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
          </Info>

          <Card title="Documentation" icon="book" href="/5.9/docs/projects/runtime/ui-flow-sessions">
            See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Session monitoring" icon="eye">
              View all active and historical UI Flow sessions with status, start date, and session IDs
            </Card>

            <Card title="Audit log" icon="clipboard-list">
              Comprehensive audit trail showing all events and actions within each session
            </Card>

            <Card title="Process tracking" icon="diagram-project">
              Monitor process instances started from UI Flows with execution status and timing
            </Card>

            <Card title="Workflow debugging" icon="bug">
              View workflow execution details, node timing, and data transformations for troubleshooting
            </Card>

            <Card title="Filtering and search" icon="filter">
              Filter sessions by UI Flow definition and search by session ID for quick access
            </Card>

            <Card title="Real-time status" icon="clock">
              Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Session monitoring" icon="chart-line">
              Monitor active sessions to understand user engagement and identify sessions needing attention
            </Card>

            <Card title="Audit and compliance" icon="shield-check">
              Track all user interactions and actions for audit purposes and compliance requirements
            </Card>

            <Card title="Debugging" icon="bug">
              Investigate issues by reviewing audit logs, process instances, and workflow executions
            </Card>

            <Card title="Performance analysis" icon="gauge">
              Analyze session duration, process start times, and workflow execution performance
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="monitor">Runtime Management</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Tables in Collections**

    <Card title="Tables in Collections" icon="table">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.

          <Info>
            You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
          </Info>

          <Card title="Table Documentation" icon="book" href="/5.1/docs/building-blocks/ui-designer/ui-component-types/table">
            See the complete Table component documentation for configuration details and usage examples.
          </Card>

          <Card title="Collection Documentation" icon="book" href="/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection">
            Learn about Collection components and how to configure collection prototypes.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Table in collection items" icon="layer-group">
              Embed Table components within Collection prototypes to display structured data for each collection item
            </Card>

            <Card title="Structured data display" icon="table-columns">
              Present complex data structures with columns, rows, and table-specific formatting within collections
            </Card>

            <Card title="Table features" icon="sliders">
              Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
            </Card>

            <Card title="Dynamic content" icon="arrows-rotate">
              Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Use Cases">
          <CardGroup>
            <Card title="Product catalogs" icon="shopping-cart">
              Display product information in table format within a collection of products
            </Card>

            <Card title="Data dashboards" icon="chart-pie">
              Create dashboard views with multiple tables showing different data sets in collection items
            </Card>

            <Card title="Report listings" icon="file-lines">
              Show report summaries in table format within a collection of reports
            </Card>

            <Card title="Comparison views" icon="code-compare">
              Compare multiple entities side-by-side using tables within collection items
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Platform & infrastructure">
    Backend optimizations, connector improvements, and platform stability enhancements.

    🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
    ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
    ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling

    ### **Connector topic pattern**

    <Card title="Connector topic pattern" icon="plug">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
        </Tab>

        <Tab title="Problem Solved">
          **Previous Limitations:**

          <CardGroup>
            <Card title="Shared topic pattern" icon="share-nodes">
              Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
            </Card>

            <Card title="Security concerns" icon="shield-exclamation">
              Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Solution">
          **New Configuration:**

          ```yaml theme={"system"}
          # Old configuration (shared with all components)
          KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*

          # New configuration (dedicated for connectors)
          KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
          ```

          **Benefits:**

          * Connectors can use custom topic patterns
          * Other components continue using the standard pattern
          * Improved security through topic isolation
        </Tab>
      </Tabs>

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="building">Self-Managed</Badge>
    </Card>

    ***

    ### **Kafka configuration alignment**

    <Card title="Kafka configuration alignment" icon="plug">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
        </Tab>

        <Tab title="New Properties">
          **Standardized Kafka Properties:**

          The following new environment variables are now available across all services:

          | Environment Variable      | Description                               | Fallback Property                |
          | ------------------------- | ----------------------------------------- | -------------------------------- |
          | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers     | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
          | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |

          <Info>
            The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
          </Info>
        </Tab>

        <Tab title="Benefits">
          <CardGroup>
            <Card title="Property alignment" icon="link">
              Consistent property names across core-services and AI platform services
            </Card>

            <Card title="Backwards compatible" icon="arrow-left">
              Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
            </Card>

            <Card title="Simplified configuration" icon="sliders">
              Unified configuration approach across all FlowX.AI services
            </Card>

            <Card title="Migration flexibility" icon="arrows-rotate">
              Migrate to new properties at your own pace without breaking existing deployments
            </Card>
          </CardGroup>

          <Info>
            This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
          </Info>
        </Tab>
      </Tabs>

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Advancing performance**

    <Card title="Advancing performance" icon="gauge-high">
      FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.

      <Accordion title="Stalled events fix">
        Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
      </Accordion>

      <Accordion title="Numeric overflow fix">
        Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
      </Accordion>

      <Accordion title="Concurrency improvements">
        * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
        * Replaced trigger-based solution with SQL transactions for atomic updates
        * Improved handling of embedded subprocess completion under concurrent load
      </Accordion>

      <Accordion title="Automated test stability">
        Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
      </Accordion>

      <Badge icon="bolt">Performance</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Bug fixes & stability">
    Comprehensive bug fixes across SaaS features, Designer, and backend services.

    🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
    ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements

    ### **Designer fixes**

    <Card title="Designer fixes" icon="palette">
      FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.

      ## Navigation & routing

      <Accordion title="Navigation fixes">
        * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
        * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
        * **Fixed back navigation** - resolved 403 when going back from UI Flows page
        * **Fixed audit log access** - resolved errors when viewing process instance audit logs
        * **Fixed version history** - "Open version in new tab" now works correctly
      </Accordion>

      <Accordion title="UI improvements">
        * **Fixed default locale display** - locale now correctly shown in Version settings
        * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
      </Accordion>

      <Badge icon="palette">Designer Stability</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Backend fixes**

    <Card title="Backend fixes" icon="server">
      Backend stability and performance improvements across core services.

      ## Process engine

      <Accordion title="Advancing & concurrency">
        * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
        * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
        * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
        * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
      </Accordion>

      ## AI platform

      <Accordion title="AI integration fixes">
        * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
        * **Fixed SSE event delivery** - events are delivered individually as they complete
      </Accordion>

      ## Integration Designer

      <Accordion title="Workflow & data model">
        * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
        * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
      </Accordion>

      <Badge icon="server">Backend Stability</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Info">
    ## Additional information

    ### Deployment information

    <Info>
      For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
    </Info>

    ### Compatibility

    <CardGroup>
      <Card title="Upgrade path" icon="arrow-up-right-dots">
        Upgrade from v5.3.0 - no breaking changes for standard deployments
      </Card>

      <Card title="Component compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
      </Card>
    </CardGroup>

    ### SaaS features

    <Info>
      The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.
    </Info>
  </Tab>
</Tabs>


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5



<Info>
  After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Component versions

| Component                  | 5.5.0       | 5.4.0   | 5.3.0   | 5.2.0   | 5.1.1   | 5.1.0   |
| -------------------------- | ----------- | ------- | ------- | ------- | ------- | ------- |
| **process-engine**         | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3  | 9.63.0  |
| **admin**                  | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5  | 9.65.0  |
| **designer**               | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core**               | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0  | 9.36.3  | 9.35.0  |
| **scheduler-core**         | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1  | 9.26.1  | 9.25.0  |
| **events-gateway**         | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1  | 9.26.1  | 9.25.0  |
| **notification-plugin**    | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0  | 9.29.1  | 9.28.0  |
| **document-plugin**        | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0  | 9.35.1  | 9.34.0  |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0  | 9.34.2  | 9.33.0  |
| **data-search**            | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1  | 9.23.1  | 9.22.0  |
| **audit-core**             | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0  | 9.30.1  | 9.29.1  |
| **advancing-controller**   | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1  | 9.25.1  | 9.24.0  |
| **integration-designer**   | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0  | 9.50.0  | 9.49.1  |
| **application-manager**    | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6  | 9.72.0  |
| **runtime-manager**        | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6  | 9.72.0  |
| **data-sync**              | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1  | 9.22.1  | 9.21.0  |
| **authorization-system**   | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0  | 9.34.2  | 9.33.0  |
| **nosql-db-runner**        | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1  | 9.22.1  | 9.21.0  |
| **email-gateway**          | **10.24.0** | 10.9.0  | -       | -       | -       | -       |
| **organization-manager**   | **10.19.2** | -       | -       | -       | -       | -       |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component                     | 5.5.0       | 5.4.0   | 5.3.0   | 5.2.0   | 5.1.1   | 5.1.0   |
| ----------------------------- | ----------- | ------- | ------- | ------- | ------- | ------- |
| **@flowx/angular-sdk**        | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme**      | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk**          | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme**        | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit**   | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk**           | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme**         | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer**              | **10.3.0**  | 10.2.0  | 10.1.0  | 10.0.0  | 9.0.5   | 9.0.4   |
| **Android renderer**          | **10.3.0**  | 10.2.0  | 10.1.0  | 10.0.0  | 9.0.3   | 9.0.2   |

### Plugins

| Component            | 5.5.0  | 5.4.0  | 5.3.0  | 5.2.0  | 5.1.1  | 5.1.0  |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.5.0      | 5.4.0  | 5.3.0  | 5.2.0  | 5.1.1 | 5.1.0 |
| ------------------------------- | ---------- | ------ | ------ | ------ | ----- | ----- |
| **ai-assistant**                | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform**                 | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer**    | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents**          | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations**   | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models**          | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants**         | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner**         | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst**      | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer**     | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder**   | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries**        | **TBD**    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase**               | **TBD**    | -      | -      | -      | -     | -     |
| **knowledgebase-rag**           | **10.2.0** | -      | -      | -      | -     | -     |
| **knowledgebase-indexer-v2**    | **10.2.0** | -      | -      | -      | -     | -     |
| **mcp**                         | **10.2.0** | -      | -      | -      | -     | -     |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.5.0            | Keycloak             | 26+                |
| 5.5.0            | Kafka                | 3.8 - 3.9          |
| 5.5.0            | PostgreSQL           | 16 - 17            |
| 5.5.0            | Oracle Database      | 21c, 23ai          |
| 5.5.0            | MongoDB              | 7 - 8              |
| 5.5.0            | Redis                | 7.4 - 8.0          |
| 5.5.0            | Elasticsearch        | 8 - 9              |
| 5.5.0            | Angular (Web SDK)    | 20                 |
| 5.5.0            | React (Web SDK)      | 18.x               |

<Warning>
  Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:

  * Keycloak versions older than 26
  * Kafka versions older than 3.8
  * Redis versions older than 7.4
</Warning>

## New in v5.5.0

### Key features and updates

<CardGroup>
  <Card title="Chat Component Enhancements" icon="comments">
    New subcomponents (reasoning, error, suggestions), display modes, and mobile support
  </Card>

  <Card title="UI Flows Improvements" icon="route">
    Process renderer component, start workflow action, and on load events
  </Card>

  <Card title="Microsoft Outlook Integration" icon="envelope">
    Native MS Graph data source for reading and sending Outlook emails
  </Card>

  <Card title="Send Notification Action" icon="paper-plane">
    Send emails and reply to received emails directly from processes via SMTP
  </Card>

  <Card title="Knowledge Base v2" icon="book-open">
    Updated Knowledge Base with audit, resource management, and improved UI
  </Card>

  <Card title="User Management Updates" icon="users-gear">
    Password policy, DISABLED status, resend invitations, workspace environment types
  </Card>
</CardGroup>

## Upgrading from v5.4.0

### Breaking changes

<Warning>
  FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.
</Warning>

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable                                                    | Description                                  | Previously Used By |
| ----------------------------------------------------------------------- | -------------------------------------------- | ------------------ |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint          | 14 services        |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID`         | Client ID for opaque-token introspection     | 14 services        |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET`     | Client secret for opaque-token introspection | 14 services        |
| `SECURITY_OAUTH2_REALM`                                                 | OAuth2 realm name                            | 13 services        |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID`                                      | OAuth2 client ID                             | 13 services        |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`                                  | OAuth2 client secret                         | 13 services        |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`                       | Service account admin client ID              | 8 services         |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`                   | Service account admin client secret          | 8 services         |

**Changed default values:**

| Environment Variable                                                    | Old Default                                              | New Default                           | Affected Services |
| ----------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------- | ----------------- |
| `SECURITY_TYPE`                                                         | `oauth2`                                                 | `jwt-public-key`                      | 14/19 services    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID`     | `${security.oauth2.service-account.admin.client-id}`     | `flowx-${spring.application.name}-sa` | 8 services        |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-`                                   | 8 services        |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI`     | Uses `${security.oauth2.realm}`                          | Uses `${security.oauth2.sa-realm}`    | 8 services        |

<Info>
  A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.
</Info>

**Migration steps:**

<Steps>
  <Step title="Update SECURITY_TYPE if explicitly set">
    If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.
  </Step>

  <Step title="Remove deprecated opaque-token variables">
    Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.
  </Step>

  <Step title="Update service account client IDs">
    Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.
  </Step>

  <Step title="Configure the service account realm">
    Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.
  </Step>

  <Step title="Remove legacy OAuth2 client variables">
    Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.
  </Step>
</Steps>

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

<Info>
  **Available starting with FlowX.AI 5.5.0**

  The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.
</Info>

**Infrastructure requirements:**

| Dependency   | Details                                      |
| ------------ | -------------------------------------------- |
| PostgreSQL   | Dedicated database for organization data     |
| Redis        | Caching and session management               |
| Kafka        | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management          |
| SpiceDB      | Authorization via CAS lib                    |

<Card title="Organization Manager Setup" icon="building" href="/5.1/setup-guides/organization-manager-setup">
  Complete setup and configuration guide for the Organization Manager microservice
</Card>

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name                                                     | Description                                                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1`             | Triggers file decryption operations                                                            |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1`             | Triggers file encryption operations                                                            |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1`    | Triggers bulk document persistence operations                                                  |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name                                                                 | Description                                                                    |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1`          | Results from file decryption operations                                        |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1`          | Results from file encryption operations                                        |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence                                         |
| `ai.flowx.eventsgateway.receive.document.v1`                               | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

<Info>
  The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.
</Info>

**New topics:**

| Topic Name                                                                        | Description                           | Direction |
| --------------------------------------------------------------------------------- | ------------------------------------- | --------- |
| `ai.flowx.application-version.sync.system.in.v1`                                  | System resource sync requests         | Inbound   |
| `ai.flowx.application-version.sync.workflow.in.v1`                                | Workflow resource sync requests       | Inbound   |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1`   | System resource correction requests   | Inbound   |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound   |
| `ai.flowx.build.runtime-data.v1`                                                  | Build runtime data                    | Outbound  |
| `ai.flowx.license.usage.v1`                                                       | License usage tracking                | Outbound  |

**Existing topics (new producer in 5.5.0):**

| Topic Name                                                                | Description                    | Direction |
| ------------------------------------------------------------------------- | ------------------------------ | --------- |
| `ai.flowx.application-version.sync.out.v1`                                | Sync operation responses       | Outbound  |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound  |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

<Info>
  The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.
</Info>

| Topic Name                                                                       | Description                 | Direction |
| -------------------------------------------------------------------------------- | --------------------------- | --------- |
| `ai.flowx.application-version.sync.ui-flow.in.v1`                                | UI flow sync requests       | Inbound   |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound   |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

<Info>
  Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.
</Info>

| Topic Name                                                                        | Description                  | Direction |
| --------------------------------------------------------------------------------- | ---------------------------- | --------- |
| `ai.flowx.application-version.sync.system.in.v1`                                  | System resource sync         | Outbound  |
| `ai.flowx.application-version.sync.workflow.in.v1`                                | Workflow resource sync       | Outbound  |
| `ai.flowx.application-version.sync.ui-flow.in.v1`                                 | UI flow resource sync        | Outbound  |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1`   | System correction requests   | Outbound  |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound  |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1`  | UI flow correction requests  | Outbound  |

#### Email-gateway Kafka topics

| Topic Name                                         | Description                             | Direction |
| -------------------------------------------------- | --------------------------------------- | --------- |
| `ai.flowx.core.trigger.save.audit.v1`              | Audit event logging                     | Outbound  |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound  |

#### Authorization-system Kafka topics

| Topic Name                        | Description                   | Direction |
| --------------------------------- | ----------------------------- | --------- |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound  |

#### Notification-plugin Kafka topics

| Topic Name                                                                     | Description                       | Direction |
| ------------------------------------------------------------------------------ | --------------------------------- | --------- |
| `ai.flowx.application-version.resources-usages.refresh.v1`                     | Resource usages refresh events    | Inbound   |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound  |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1`             | Bulk resource usage operations    | Outbound  |

<Info>
  These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.
</Info>

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable       | Description                                      | Default Value      | Component                                                                                                                             |
| -------------------------- | ------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `KAFKA_MESSAGE_MAX_BYTES`  | Maximum Kafka producer message size in bytes     | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL`                | Redis cache time-to-live in milliseconds         | `5000000`          | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin                               |
| `KAFKA_OAUTH_CLIENT_ID`    | OAuth client ID for Kafka SASL authentication    | `kafka`            | events-gateway, email-gateway, notification-plugin, document-plugin                                                                   |
| `LOGGING_LEVEL_APP`        | Application-specific logging level               | `INFO`             | Most services (12/19)                                                                                                                 |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF`              | Most services (12/19)                                                                                                                 |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level                     | `INFO`             | admin, application-manager, cms-core                                                                                                  |

#### Document-plugin variables

| Environment Variable        | Description                                        | Default Value      | Component       |
| --------------------------- | -------------------------------------------------- | ------------------ | --------------- |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

<Info>
  This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).
</Info>

#### Authorization-system variables

| Environment Variable                                | Description                                                                                                                              | Default Value | Component            |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------- |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty)   | authorization-system |

<Warning>
  **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).

  Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.
</Warning>

<Card title="Authorization System Setup" icon="shield-halved" href="/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris">
  See the full redirect URI configuration details
</Card>

#### Email-gateway variables

| Environment Variable                           | Description                                                    | Default Value    | Component     |
| ---------------------------------------------- | -------------------------------------------------------------- | ---------------- | ------------- |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT`        | IMAP server connection timeout in milliseconds                 | `10000`          | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS`      | Maximum number of concurrent IMAP polling operations           | `30`             | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL`     | Maximum messages to fetch per polling cycle                    | `50`             | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL`          | Interval between IMAP polling cycles in seconds                | `30`             | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT`              | IMAP read timeout in milliseconds                              | `30000`          | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON`           | Cron expression for master election checks                     | `*/5 * * * * *`  | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL`            | Master election TTL in seconds                                 | `15`             | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE`        | Maximum email accounts per service instance for load balancing | `100`            | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON`               | Cron expression for email account rebalancing                  | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS`          | Timeout in seconds before marking an instance as stale         | `90`             | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle           | `50`             | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL`      | TTL for cached MS Graph client instances                       | `1d`             | email-gateway |

<Info>
  For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.1/setup-guides/email-gateway-setup) guide.
</Info>

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

<Info>
  For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.
</Info>

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

<Warning>
  FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.
</Warning>

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

<Warning>
  **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.

  If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.
</Warning>

## Migration process

<Steps>
  <Step title="Back up your configuration">
    Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.
  </Step>

  <Step title="Update Keycloak service accounts">
    Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.
  </Step>

  <Step title="Update environment variables">
    Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.
  </Step>

  <Step title="Deploy Organization Manager">
    If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.
  </Step>

  <Step title="Deploy and verify">
    Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.
  </Step>
</Steps>

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

<Info>
  A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.
</Info>

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable                                                    | Description                                  | Previously Used By |
| ----------------------------------------------------------------------- | -------------------------------------------- | ------------------ |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint          | 14 services        |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID`         | Client ID for opaque-token introspection     | 14 services        |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET`     | Client secret for opaque-token introspection | 14 services        |
| `SECURITY_OAUTH2_REALM`                                                 | OAuth2 realm name                            | 13 services        |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID`                                      | OAuth2 client ID                             | 13 services        |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`                                  | OAuth2 client secret                         | 13 services        |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`                       | Service account admin client ID              | 8 services         |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`                   | Service account admin client secret          | 8 services         |

### Changed default values

| Environment Variable                                                    | Old Default                                              | New Default                           | Affected Services |
| ----------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------- | ----------------- |
| `SECURITY_TYPE`                                                         | `oauth2`                                                 | `jwt-public-key`                      | 14/19 services    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID`     | `${security.oauth2.service-account.admin.client-id}`     | `flowx-${spring.application.name}-sa` | 8 services        |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-`                                   | 8 services        |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI`     | Uses `${security.oauth2.realm}`                          | Uses `${security.oauth2.sa-realm}`    | 8 services        |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service                | New Client ID                     |
| ---------------------- | --------------------------------- |
| Admin                  | `flowx-admin-sa`                  |
| Process Engine         | `flowx-process-engine-sa`         |
| Integration Designer   | `flowx-integration-designer-sa`   |
| Authorization System   | `flowx-authorization-system-sa`   |
| Runtime Manager        | `flowx-runtime-manager-sa`        |
| Scheduler Core         | `flowx-scheduler-core-sa`         |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager   | `flowx-organization-manager-sa`   |
| License                | `flowx-license-sa`                |
| Email Gateway          | `flowx-email-gateway-sa`          |

<Warning>
  Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.
</Warning>

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

<Warning>
  **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.
</Warning>

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

<Info>
  Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.
</Info>

***

## Additional resources

<CardGroup>
  <Card title="Update Environment Variables" href="./update-environment-variables-5.5" icon="list-check">
    Per-service environment variable changes for v5.5.0
  </Card>

  <Card title="Deployment Guidelines v5.5.0" href="../deployment-guidelines-v5.5" icon="rocket">
    Component versions and deployment instructions
  </Card>

  <Card title="IAM Configuration" href="/5.1/setup-guides/access-management/configuring-an-iam-solution" icon="key">
    Keycloak setup and service account configuration
  </Card>

  <Card title="Release Notes v5.5.0" href="../v5.5.0-february-2026" icon="file-lines">
    Full release notes for v5.5.0
  </Card>
</CardGroup>

## Support

<Info>
  For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.
</Info>


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

<Info>
  This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).
</Info>

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"system"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

<Tabs>
  <Tab title="Before (v5.4)">
    ```yaml theme={"system"}
    SECURITY_TYPE: "oauth2"

    # Service account client ID (example for admin service)
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"

    # Token URI using main realm
    SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
    ```
  </Tab>

  <Tab title="After (v5.5)">
    ```yaml theme={"system"}
    SECURITY_TYPE: "jwt-public-key"

    # Service account client ID follows flowx-{service-name}-sa pattern
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"

    # Token URI now uses separate sa-realm
    SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
    ```
  </Tab>
</Tabs>

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable       | Description                                      | Default Value      | Component                                                                                                                             |
| -------------------------- | ------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `KAFKA_MESSAGE_MAX_BYTES`  | Maximum Kafka producer message size in bytes     | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL`                | Redis cache time-to-live in milliseconds         | `5000000`          | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin                               |
| `KAFKA_OAUTH_CLIENT_ID`    | OAuth client ID for Kafka SASL authentication    | `kafka`            | events-gateway, email-gateway, notification-plugin, document-plugin                                                                   |
| `LOGGING_LEVEL_APP`        | Application-specific logging level               | `INFO`             | Most services (12/19)                                                                                                                 |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF`              | Most services (12/19)                                                                                                                 |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level                     | `INFO`             | admin, application-manager, cms-core                                                                                                  |

***

## Document plugin

| Environment Variable        | Description                                        | Default Value      |
| --------------------------- | -------------------------------------------------- | ------------------ |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

<Info>
  **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.
</Info>

| Environment Variable                       | Description                                                    | Default Value    |
| ------------------------------------------ | -------------------------------------------------------------- | ---------------- |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT`    | IMAP server connection timeout in milliseconds                 | `10000`          |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS`  | Maximum number of concurrent IMAP polling operations           | `30`             |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle                    | `50`             |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL`      | Interval between IMAP polling cycles in seconds                | `30`             |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT`          | IMAP read timeout in milliseconds                              | `30000`          |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON`       | Cron expression for master election checks                     | `*/5 * * * * *`  |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL`        | Master election TTL in seconds                                 | `15`             |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE`    | Maximum email accounts per service instance for load balancing | `100`            |
| `EMAIL_GATEWAY_REBALANCING_CRON`           | Cron expression for email account rebalancing                  | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS`      | Timeout in seconds before marking an instance as stale         | `90`             |

***

## Additional resources

<CardGroup>
  <Card title="Migration Overview" href="./migration-overview" icon="book">
    Full migration guide with Keycloak and service account changes
  </Card>

  <Card title="Deployment Guidelines v5.5.0" href="../deployment-guidelines-v5.5" icon="rocket">
    Component versions, Kafka topics, and infrastructure requirements
  </Card>
</CardGroup>


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

<Info>
  FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.
</Info>

<Frame>
  ![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)
</Frame>

**What's new?**

<Tabs>
  <Tab title="AI Platform">
    AI-powered features and document processing enhancements.

    📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
    📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI

    ### **Extract Data from File**

    <Card title="Extract Data from File" icon="file-lines">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.

          <Card title="Documentation" icon="book" href="/5.9/ai-platform/agent-builder/extract-data-from-file">
            See the complete Extract Data from File documentation.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Extraction strategies" icon="sliders">
              Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
            </Card>

            <Card title="Image support" icon="image">
              Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
            </Card>

            <Card title="Image extraction options" icon="magnifying-glass">
              Extract data from embedded images or generate image descriptions
            </Card>

            <Card title="Signature detection" icon="signature">
              Detect and locate signatures within documents (LLM and OCR modes)
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Extraction strategies:**

          | Strategy     | Best for                          | Speed  | Cost   | Accuracy   |
          | ------------ | --------------------------------- | ------ | ------ | ---------- |
          | LLM Model    | Complex layouts, handwritten text | Slow   | High   | High       |
          | OCR Engine   | Scanned documents                 | Medium | Medium | Medium     |
          | Text Parsing | Clean digital PDFs                | Fast   | Free   | Low–Medium |

          **Image extraction options (LLM and OCR only):**

          | Option            | Description                           |
          | ----------------- | ------------------------------------- |
          | Image Description | Generates text descriptions of images |
          | Image Content     | Extracts text and data from images    |

          <Tip>
            A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
          </Tip>
        </Tab>
      </Tabs>

      <Badge icon="robot">AI Integration</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Knowledge Base v2**

    <Card title="Knowledge Base v2" icon="book-open" href="/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Updated UI" icon="browser">
              Refreshed Knowledge Base interface with improved navigation and search
            </Card>

            <Card title="Audit trail" icon="clipboard-list">
              Track changes to Knowledge Base entries with full audit history
            </Card>

            <Card title="Resource management" icon="folder-open">
              Improved management of Knowledge Base resources and documents
            </Card>

            <Card title="Version tracking" icon="code-branch">
              Version-aware Knowledge Base entries tied to app versions
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="robot">AI Integration</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="UI Flows">
    Enhanced UI Flows with new components, actions, and chat improvements.

    💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
    🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
    📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
    🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
    ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load

    ### **Chat component enhancements**

    <Card title="Chat component enhancements" icon="comments" href="/5.9/ai-platform/chat-component">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
        </Tab>

        <Tab title="New Subcomponents">
          <CardGroup>
            <Card title="Reasoning display" icon="brain">
              Show AI reasoning and thought process to users for transparency
            </Card>

            <Card title="Error handling" icon="triangle-exclamation">
              Graceful error display with retry options and helpful messages
            </Card>

            <Card title="Suggestions" icon="lightbulb">
              Display suggested responses or actions to guide user interactions
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Display Modes">
          **Available display modes:**

          | Mode            | Description                                              |
          | --------------- | -------------------------------------------------------- |
          | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
          | **Sidebar**     | Chat appears as a collapsible sidebar                    |
          | **Floating**    | Chat appears as a floating widget                        |
          | **Embedded**    | Chat embedded within a container component               |
        </Tab>

        <Tab title="Mobile Support">
          The Chat component is now fully supported on mobile platforms:

          <CardGroup>
            <Card title="iOS" icon="apple">
              Native iOS renderer support with optimized touch interactions
            </Card>

            <Card title="Android" icon="android">
              Native Android renderer support with material design integration
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="robot">AI Integration</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **UI Flows breadcrumbs**

    <Card title="UI Flows breadcrumbs" icon="route" href="/5.9/docs/building-blocks/ui-flows#breadcrumbs">
      FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.

      <CardGroup>
        <Card title="Navigation path" icon="route">
          Display the full navigation path within UI Flows
        </Card>

        <Card title="Click navigation" icon="mouse-pointer">
          Navigate to any parent screen by clicking breadcrumb items
        </Card>

        <Card title="Theme configuration" icon="palette">
          Customize breadcrumb appearance through Admin theme settings
        </Card>

        <Card title="Responsive design" icon="mobile">
          Breadcrumbs adapt to different screen sizes
        </Card>
      </CardGroup>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Process renderer component**

    <Card title="Process renderer component" icon="window-restore" href="/5.9/docs/building-blocks/ui-flows#process-renderer-component">
      <Tabs>
        <Tab title="Overview">
          Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Process embedding" icon="window-restore">
              Embed any process renderer within a UI Flow screen
            </Card>

            <Card title="Data passing" icon="arrow-right-arrow-left">
              Pass data between UI Flows and embedded processes
            </Card>

            <Card title="Event handling" icon="bolt">
              Handle process events within the UI Flow context
            </Card>

            <Card title="Consistent styling" icon="link">
              Maintain consistent styling and navigation across UI Flows and processes
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Start workflow action**

    <Card title="Start workflow action" icon="play" href="/5.1/docs/building-blocks/actions/start-integration-workflow">
      <Tabs>
        <Tab title="Overview">
          Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Workflow selection" icon="list">
              Select from available integration workflows
            </Card>

            <Card title="Input mapping" icon="arrow-right">
              Map UI Flow data to workflow input parameters
            </Card>

            <Card title="Response handling" icon="arrow-left">
              Handle workflow responses and update UI state
            </Card>

            <Card title="Error handling" icon="triangle-exclamation">
              Configure error handling for failed workflow executions
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ### **On load UI event**

    <Card title="On load UI event" icon="bolt" href="/5.9/docs/building-blocks/ui-designer/ui-events#on-load-event">
      <Tabs>
        <Tab title="Overview">
          Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Automatic execution" icon="play">
              Actions execute automatically when the screen loads
            </Card>

            <Card title="Data initialization" icon="database">
              Fetch and initialize data when entering a screen
            </Card>

            <Card title="Conditional logic" icon="code-branch">
              Execute different actions based on conditions
            </Card>

            <Card title="Loading states" icon="spinner">
              Manage loading states during initialization
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Integrations">
    Email integrations, document processing, and Integration Designer updates.

    📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
    📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
    🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
    🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
    🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin

    ### **Microsoft Outlook data source**

    <Card title="Microsoft Outlook data source" icon="envelope">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.

          <Card title="Documentation" icon="book" href="/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source">
            See the complete Microsoft Outlook data source documentation.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Unified read & send" icon="arrows-left-right">
              Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
            </Card>

            <Card title="Azure AD authentication" icon="key">
              Service account authentication with Tenant ID, Client ID, and Client Secret
            </Card>

            <Card title="Email monitoring" icon="inbox">
              Monitor Outlook mailboxes and trigger processes automatically when emails arrive
            </Card>

            <Card title="Send & reply" icon="reply">
              Send new emails or reply to received emails with conversation thread support
            </Card>

            <Card title="Attachment validations" icon="paperclip">
              Configure allowed file types, max file size, and max file count for incoming emails
            </Card>

            <Card title="Test connection" icon="plug">
              Validate Azure AD credentials and MS Graph permissions before saving
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Azure AD Authentication:**

          | Field         | Description                      |
          | ------------- | -------------------------------- |
          | Tenant ID     | Azure AD tenant ID               |
          | Client ID     | Azure AD application (client) ID |
          | Client Secret | Azure AD client secret           |

          **Scope Options:**

          | Scope              | MS Graph Permissions Required                      |
          | ------------------ | -------------------------------------------------- |
          | Read Emails        | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
          | Send Emails        | `Mail.Send` or `Mail.ReadWrite`                    |
          | Read & Send Emails | One read + one send permission                     |
        </Tab>
      </Tabs>

      <Badge icon="star">Major Feature</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Send Notification action**

    <Card title="Send Notification action" icon="paper-plane">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.

          <Info>
            Existing notification templates configured for Kafka-based sending continue to work without modification.
          </Info>

          <Card title="Documentation" icon="book" href="/5.1/docs/building-blocks/actions/send-notification-action">
            See the complete Send Notification action documentation.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Email Sender data source" icon="envelope">
              New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
            </Card>

            <Card title="Reply to emails" icon="reply">
              Reply to emails that triggered the process, maintaining conversation threads
            </Card>

            <Card title="Send new emails" icon="paper-plane">
              Send new outbound emails to specified recipients with CC/BCC support
            </Card>

            <Card title="Notification template updates" icon="file-lines">
              New Email Server and Email Sender fields for direct SMTP delivery
            </Card>

            <Card title="Attachments" icon="paperclip">
              Attach files using static paths or process variable keys
            </Card>

            <Card title="Backwards compatible" icon="shield-check">
              Existing Kafka-based notification templates continue to work unchanged
            </Card>
          </CardGroup>
        </Tab>

        <Tab title="Configuration">
          **Email Sender Data Source (new):**

          | Field       | Description                               |
          | ----------- | ----------------------------------------- |
          | Protocol    | SMTP (only option)                        |
          | Server Host | SMTP server hostname                      |
          | SSL/TLS     | Enable secure connection (default: on)    |
          | Port        | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
          | Username    | Email account username                    |
          | Password    | Email account password                    |

          **Send Notification Action:**

          | Field                    | Description                                                |
          | ------------------------ | ---------------------------------------------------------- |
          | Notification Template    | Select a template with Predefined Email Connection         |
          | Reply to received emails | Toggle on to reply to the email that triggered the process |
          | Reply to Email Header    | Process variable with original email headers (reply mode)  |
          | Receivers                | Recipient email addresses or process variables             |
          | CC/BCC Receivers         | Optional CC and BCC recipients                             |
          | Language                 | Process variable key for template language                 |
          | Attachments              | File path or process variable key                          |
          | Template Data            | JSON key-value pairs for dynamic template content          |

          <Tip>
            Available on Send Message Task, Task, and User Task nodes.
          </Tip>
        </Tab>
      </Tabs>

      <Badge icon="star">Major Feature</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Integration Designer improvements**

    <Card title="Integration Designer improvements" icon="plug">
      FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.

      <CardGroup>
        <Card title="Query parameter encoding" icon="code">
          Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
        </Card>

        <Card title="REST Content-Type handling" icon="file-code">
          Improved error handling when REST endpoints return responses with unexpected Content-Type headers
        </Card>

        <Card title="Config param autocomplete" icon="wand-magic-sparkles">
          Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
        </Card>
      </CardGroup>

      <Info>
        See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
      </Info>

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Security details in workflows**

    <Card title="Security details in workflows" icon="key">
      Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.

      Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:

      ```json theme={"system"}
      {
        "securityDetails": {
          "username": "user@email.com",
          "identifier": "keycloak-subject-id",
          "details": {
            "firstName": "John",
            "lastName": "Snow",
            "email": "user@email.com"
          }
        }
      }
      ```

      <Info>
        See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
      </Info>

      <Badge icon="star">New Feature</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **File encrypt and decrypt**

    <Card title="File encrypt and decrypt" icon="lock-keyhole" href="/5.1/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files">
      FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.

      <CardGroup>
        <Card title="File encryption" icon="lock">
          Encrypt files using configurable encryption algorithms before storage
        </Card>

        <Card title="File decryption" icon="unlock">
          Decrypt files for authorized access within process flows
        </Card>
      </CardGroup>

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***
  </Tab>

  <Tab title="Platform & Management">
    User management, workspace configuration, rendering, and platform improvements.

    🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
    🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
    🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
    📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
    🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
    🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
    ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
    🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
    📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
    📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy

    ### **Container app authentication**

    <Card title="Container app authentication" icon="lock" href="/5.9/docs/saas/container-app-authentication">
      <Tabs>
        <Tab title="Overview">
          Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Authentication providers" icon="key">
              Support for multiple authentication providers
            </Card>

            <Card title="Custom landing page" icon="house">
              Customize the landing page for unauthenticated users
            </Card>

            <Card title="Session management" icon="id-badge">
              Improved session handling and token refresh
            </Card>

            <Card title="SSO integration" icon="right-to-bracket">
              Seamless single sign-on integration
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Password policy updates**

    <Card title="Password policy updates" icon="key" href="/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy">
      FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.

      **New requirements:**

      | Rule           | Value                                                            |
      | -------------- | ---------------------------------------------------------------- |
      | Minimum length | 8 characters                                                     |
      | Maximum length | 64 characters                                                    |
      | Complexity     | Must include uppercase, lowercase, number, and special character |

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **User status DISABLED**

    <Card title="User status DISABLED" icon="user-slash" href="/5.9/docs/saas/inviting-users#disabled-status">
      FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Resend user invitation**

    <Card title="Resend user invitation" icon="envelope-circle-check" href="/5.9/docs/saas/inviting-users#resending-invitations">
      FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Workspace environment type**

    <Card title="Workspace environment type" icon="layer-group" href="/5.1/docs/projects/workspaces#workspace-environment-type">
      FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Organization ID propagation**

    <Card title="Organization ID Propagation" icon="building">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
        </Tab>

        <Tab title="Key Changes">
          <CardGroup>
            <Card title="Scheduler execution" icon="clock">
              Organization ID added to scheduled job context
            </Card>

            <Card title="Event listeners" icon="bolt">
              Organization ID propagated to event handlers
            </Card>

            <Card title="Process instances" icon="diagram-project">
              Organization ID captured from initiator
            </Card>

            <Card title="Audit trail" icon="clipboard-list">
              Enhanced audit logging with organization context
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="gear">Infrastructure</Badge>
      <Badge icon="cloud">SaaS</Badge>
    </Card>

    ***

    ### **Rendering runtime UX**

    <Card title="Rendering runtime UX" icon="gauge-high">
      FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.

      <CardGroup>
        <Card title="Loading states" icon="spinner">
          Improved loading state indicators and skeleton screens
        </Card>

        <Card title="Transition animations" icon="wand-magic-sparkles">
          Smoother transitions between screens and states
        </Card>

        <Card title="Error boundaries" icon="shield">
          Better error handling with graceful degradation
        </Card>

        <Card title="Performance" icon="bolt">
          Optimized rendering performance for complex UIs
        </Card>
      </CardGroup>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Process variables compare**

    <Card title="Process variables compare" icon="code-compare" href="/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view">
      FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.

      <CardGroup>
        <Card title="Diff editor" icon="code-compare">
          Side-by-side comparison of process variable values using Monaco diff editor
        </Card>

        <Card title="Version comparison" icon="code-branch">
          Compare variable values across different process versions
        </Card>
      </CardGroup>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Failed email trigger details page**

    <Card title="Failed email trigger details page" icon="envelope-circle-xmark" href="/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page">
      FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### **Data Model sidepanel**

    <Card title="Data Model sidepanel" icon="panel-left">
      <Tabs>
        <Tab title="Overview">
          FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.

          <Card title="Process Data Model" icon="book" href="/5.1/docs/building-blocks/process/data-model#data-model-interface">
            See the updated Process Data Model documentation.
          </Card>
        </Tab>

        <Tab title="Key Features">
          <CardGroup>
            <Card title="Attribute settings side panel" icon="panel-right">
              Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
            </Card>

            <Card title="Inline add attribute" icon="plus">
              Add attributes directly on each data type — button shows on hover after the first attribute
            </Card>

            <Card title="Attribute path copy" icon="copy">
              View and copy the full key path for any attribute for use in business rules and UI bindings
            </Card>

            <Card title="Selection highlights" icon="bullseye">
              Selecting a data type or connector highlights its location on the canvas
            </Card>

            <Card title="Default minimized panel" icon="minimize">
              The Data Types panel starts minimized by default for a cleaner canvas view
            </Card>

            <Card title="Confirmation toasts" icon="check">
              Success notifications when adding new data types
            </Card>
          </CardGroup>
        </Tab>
      </Tabs>

      <Badge icon="sparkles">UI Enhancement</Badge>
      <Badge icon="globe">All Deployments</Badge>
    </Card>

    ***

    ### Additional improvements

    * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
    * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
    * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
    * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
    * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
    * **Security patches** — General security improvements across platform services
  </Tab>

  <Tab title="Info">
    ## Additional information

    ### Deployment information

    <Info>
      For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
    </Info>

    ### Compatibility

    <Warning>
      **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
    </Warning>

    <CardGroup>
      <Card title="Upgrade path" icon="arrow-up-right-dots">
        Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
      </Card>

      <Card title="Component compatibility" icon="circle-check">
        Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5
      </Card>
    </CardGroup>
  </Tab>
</Tabs>


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6



<Info>
  After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.
</Info>

<Frame>
  ![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)
</Frame>

## Component versions

| Component                  | 5.6.0        | 5.5.0   | 5.4.0   | 5.3.0   | 5.2.0   | 5.1.1   |
| -------------------------- | ------------ | ------- | ------- | ------- | ------- | ------- |
| **process-engine**         | **10.77.0**  | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3  |
| **admin**                  | **10.66.0**  | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5  |
| **designer**               | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core**               | **10.43.0**  | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0  | 9.36.3  |
| **scheduler-core**         | **10.31.0**  | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1  | 9.26.1  |
| **events-gateway**         | **10.33.1**  | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1  | 9.26.1  |
| **notification-plugin**    | **10.42.1**  | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0  | 9.29.1  |
| **document-plugin**        | **10.46.0**  | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0  | 9.35.1  |
| **task-management-plugin** | **10.41.1**  | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0  | 9.34.2  |
| **data-search**            | **10.30.1**  | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1  | 9.23.1  |
| **audit-core**             | **10.40.0**  | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0  | 9.30.1  |
| **advancing-controller**   | **10.33.1**  | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1  | 9.25.1  |
| **integration-designer**   | **10.84.0**  | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0  | 9.50.0  |
| **application-manager**    | **10.69.1**  | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6  |
| **runtime-manager**        | **10.69.1**  | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6  |
| **data-sync**              | **10.38.0**  | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1  | 9.22.1  |
| **authorization-system**   | **10.51.0**  | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0  | 9.34.2  |
| **nosql-db-runner**        | **10.34.0**  | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1  | 9.22.1  |
| **email-gateway**          | **10.32.1**  | 10.24.0 | 10.9.0  | -       | -       | -       |
| **organization-manager**   | **10.26.1**  | 10.19.2 | -       | -       | -       | -       |
| **webhook-gateway**        | **10.1.1**   | -       | -       | -       | -       | -       |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component                     | 5.6.0        | 5.5.0   | 5.4.0   | 5.3.0   | 5.2.0   | 5.1.1   |
| ----------------------------- | ------------ | ------- | ------- | ------- | ------- | ------- |
| **@flowx/angular-sdk**        | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme**      | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk**          | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme**        | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit**   | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk**           | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme**         | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer**              | **10.3.0**   | 10.3.0  | 10.2.0  | 10.1.0  | 10.0.0  | 9.0.5   |
| **Android renderer**          | **10.3.0**   | 10.3.0  | 10.2.0  | 10.1.0  | 10.0.0  | 9.0.3   |

### Plugins

| Component            | 5.6.0  | 5.5.0  | 5.4.0  | 5.3.0  | 5.2.0  | 5.1.1  |
| -------------------- | ------ | ------ | ------ | ------ | ------ | ------ |
| **ocr-plugin**       | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  | 0.2.3  |

### AI Platform

| Component                       | 5.6.0      | 5.5.0  | 5.4.0  | 5.3.0  | 5.2.0  | 5.1.1 |
| ------------------------------- | ---------- | ------ | ------ | ------ | ------ | ----- |
| **ai-assistant**                | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform**                 | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer**    | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents**          | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations**   | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models**          | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants**         | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner**         | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst**      | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer**     | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder**   | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries**        | **10.6.0** | TBD    | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase**               | **10.6.0** | TBD    | -      | -      | -      | -     |
| **knowledgebase-rag**           | **10.6.0** | 10.2.0 | -      | -      | -      | -     |
| **knowledgebase-indexer-v2**    | **10.6.0** | 10.2.0 | -      | -      | -      | -     |
| **mcp**                         | **10.6.0** | 10.2.0 | -      | -      | -      | -     |
| **doc-converter**               | **10.2.2** | -      | -      | -      | -      | -     |
| **doc-parser**                  | **10.5.1** | -      | -      | -      | -      | -     |

<Info>
  **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.
</Info>

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| ---------------- | -------------------- | ------------------ |
| 5.6.0            | Keycloak             | 26+                |
| 5.6.0            | Kafka                | 3.8 - 3.9          |
| 5.6.0            | PostgreSQL           | 16 - 17            |
| 5.6.0            | Oracle Database      | 21c, 23ai          |
| 5.6.0            | MongoDB              | 7 - 8              |
| 5.6.0            | Redis                | 7.4 - 8.0          |
| 5.6.0            | Angular (Web SDK)    | 20                 |
| 5.6.0            | React (Web SDK)      | 18.x               |

<Warning>
  Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:

  * Keycloak versions older than 26
  * Kafka versions older than 3.8
  * Redis versions older than 7.4
</Warning>

## New in v5.6.0

### Key features and updates

<CardGroup>
  <Card title="Chat Driven Workflows" icon="comments">
    Multi-turn AI conversations with session memory and intent classification
  </Card>

  <Card title="Incoming Webhooks" icon="webhook">
    Trigger processes from external HTTP POST requests via the new webhook-gateway service
  </Card>

  <Card title="Web Page Extractor" icon="globe">
    Collect readable content from web page URLs with crawling and link following
  </Card>

  <Card title="Proxy Server Connections" icon="shield-halved">
    Route integration traffic through HTTP/HTTPS proxy servers
  </Card>

  <Card title="UI Flow Route Management" icon="route">
    Query parameters, route maps, and breadcrumb navigation for UI Flows
  </Card>

  <Card title="MCP Authentication" icon="key">
    BEARER and BASIC auth for MCP server connections
  </Card>
</CardGroup>

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

<Warning>
  The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.
</Warning>

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

<Warning>
  The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.
</Warning>

***

### New environment variables

#### Integration Designer

| Environment Variable         | Description                                                    | Default Value               | Component            |
| ---------------------------- | -------------------------------------------------------------- | --------------------------- | -------------------- |
| `FLOWX_WEBHOOKS_BASE_URL`    | Base URL for webhook-gateway service communication             | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80`     | integration-designer |

#### NoSQL DB Runner

| Environment Variable                        | Description                                           | Default Value | Component       |
| ------------------------------------------- | ----------------------------------------------------- | ------------- | --------------- |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100`         | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL`         | Time-to-live for cached external MongoDB connections  | `1d`          | nosql-db-runner |

#### Process Engine

| Environment Variable        | Description                                  | Default Value | Component      |
| --------------------------- | -------------------------------------------- | ------------- | -------------- |
| `FLOWX_RETRY_MAX_RETRIES`   | Maximum retry attempts for failed operations | `9`           | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms)              | `10`          | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS`  | Maximum delay between retries (ms)           | `200`         | process-engine |

#### Authorization System

| Environment Variable                                                            | Description                                   | Default Value | Component            |
| ------------------------------------------------------------------------------- | --------------------------------------------- | ------------- | -------------------- |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD`              | Initial password for default realm admin user | *(none)*      | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login          | `true`        | authorization-system |

#### Application Manager

| Environment Variable                                                                | Description                                                  | Default Value                      | Component           |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------- | ------------------- |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD`              | Resource ID field for proxy connection merge                 | `resourceId`                       | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS`           | Flatten map ID fields for proxy connection merge             | `resourceId, name`                 | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map         | `authorization.configuration`      | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS`     | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS`   | Excluded JSON paths for proxy connection conflict detection  | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable                                          | Description                                  | Default Value                    | Component   |
| ------------------------------------------------------------- | -------------------------------------------- | -------------------------------- | ----------- |
| `FLOWX_SPICEDB_HOST`                                          | SpiceDB server hostname                      | `spicedb`                        | data-search |
| `FLOWX_SPICEDB_PORT`                                          | SpiceDB server port                          | `50051`                          | data-search |
| `FLOWX_SPICEDB_TOKEN`                                         | SpiceDB authentication token                 | - (required)                     | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable                                          | Description                                  | Default Value                    | Component     |
| ------------------------------------------------------------- | -------------------------------------------- | -------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST`                                          | SpiceDB server hostname                      | `spicedb`                        | email-gateway |
| `FLOWX_SPICEDB_PORT`                                          | SpiceDB server port                          | `50051`                          | email-gateway |
| `FLOWX_SPICEDB_TOKEN`                                         | SpiceDB authentication token                 | - (required)                     | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

<Info>
  The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.
</Info>

#### Webhook Gateway

| Environment Variable                                  | Description                                            | Default Value                                       | Component       |
| ----------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------- | --------------- |
| `SPRING_DATASOURCE_URL`                               | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME`                          | Database username                                      | `flowx`                                             | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD`                          | Database password                                      | *(required)*                                        | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL`                     | OAuth2/OIDC server base URL                            | —                                                   | webhook-gateway |
| `SECURITY_OAUTH2_REALM`                               | OAuth2 realm name                                      | —                                                   | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`     | Service account client ID                              | `flowx-webhook-gateway-sa`                          | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret                          | *(required)*                                        | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT`                       | Kafka topic for process start events                   | `ai.flowx.core.trigger.start-for-event.process.v1`  | webhook-gateway |

<Info>
  `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.
</Info>

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name                                                     | Description                                                                                    | Direction |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------- |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound   |
| `ai.flowx.eventsgateway.receive.document.v1`                   | Document events sent to events-gateway for SSE delivery                                        | Outbound  |

#### Webhook Gateway Kafka topics

| Topic Name                                         | Description                                          | Direction |
| -------------------------------------------------- | ---------------------------------------------------- | --------- |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound  |

<Info>
  The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.
</Info>

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name                                | Description                                                                   | Direction                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable                          | Description                                          | Default Value                             | Component                             |
| --------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- | ------------------------------------- |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN`                | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine                        |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`               | Topic for sending UI flow session variable updates   | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates                | `ui-flow-update`                          | process-engine                        |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates       | `6`                                       | process-engine                        |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

<Info>
  For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.
</Info>

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

<div>
  <iframe />
</div>

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

<CardGroup>
  <Card title="For AI builders" icon="robot" href="#conversational-workflows">
    Chat Driven workflows, session memory, intent routing, and context retrieval
  </Card>

  <Card title="For integrators" icon="plug" href="#incoming-webhooks">
    Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates
  </Card>

  <Card title="For UI developers" icon="palette" href="#ui-flow-session-variables">
    Session variables, route management, chat history, suggested prompts, and new UI events
  </Card>
</CardGroup>

### What changed since 5.5.0

| 5.5.0                                                | 5.6.0                                                            |
| ---------------------------------------------------- | ---------------------------------------------------------------- |
| Output Focused workflows only                        | + **Chat Driven** workflows with multi-turn memory               |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth                          |
| FlowX-managed MongoDB only                           | + **Unmanaged MongoDB** — bring your own database                |
| No conversation persistence                          | **Chat History** — browse and resume past sessions               |
| Static chat empty state                              | **Suggested Prompts** — guide users with one-click starters      |
| Certificate file paths only                          | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows                       | **Session