> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiating/starting processes

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

> [card] [User Interface](#starting-a-process-via-user-interface)
>
> The most common way to start processes through user interaction

> [card] [Kafka Messages](#starting-a-process-via-kafka)
>
> Start processes through Kafka events from other systems

> [card] [Timer Events](#timer-start-event)
>
> Schedule processes to start automatically at specific times

> [card] [Message Events](#message-catch-start-event)
>
> Trigger processes through message events from other processes

> [card] [Email Triggers](#email-and-webhook-triggers)
>
> Start processes automatically when an email arrives in a monitored inbox

> [card] [Incoming Webhooks](#email-and-webhook-triggers)
>
> Start processes from external systems through HTTP POST requests

## Starting a process via user interface

> [!WARNING]
>
> Manual Start using start parameters (JSON data) are limited to 1MB

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={"dark"}
  413 Content Too Large
  ```

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

Start Process JSON input in Designer

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

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

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

**3. Configure the Kafka Topic**

1. In the Kafka Send Action configuration, specify the topic linked to the `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN` environment variable
2. This variable is shared between the **application-manager** and **runtime-manager** deployments

![Process Start Topic Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_process_by_name_topic.png)

Process Start Topic Configuration

> [!NOTE]
>
> To verify the topic in FlowX Designer, navigate to: **Platform status → FlowX Components → application-manager-mngt -> kafkaTopicHealthCheckIndicator → details → configuration → topic → process → start-by-name**
>
> ![Topic Verification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/topic_kafka.png)
>
> Topic Verification

**4. Add Message Content**

Add any required data in the message body that should be passed to the new process:

```json theme={"dark"}
{"test": "something"}
```

> [!NOTE]
>
> This data will be available to the process being started, providing it with initial context or parameters.

**5. Respect Payload Size Limits**

> [!WARNING]
>
> **Payload Size Must Be Under 1MB**: All Kafka-triggered process starts go through the runtime HTTP API, which enforces strict 1MB payload limits.

#### 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={"dark"}
server:
  undertow:
    max-http-post-size: 2MB
```

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

![Headers Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_process_by_name_headers.png)

Headers Configuration

The headers should look something like this:

```json theme={"dark"}
{
  "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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/finding-identifiers-and-parameters.md) guide for step-by-step instructions on locating Application IDs, Process Names, JWT tokens, and more.

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

**7. 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_STARTBYNAME_OUT` topic

![Kafka Response Monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-11%20at%2017.33.58.png)

Kafka Response Monitoring

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

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

![Timer Start Event Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_timer_process.png)

Timer Start Event Configuration

**2. Configure Timer Settings**

Configure the timer according to your requirements:

1. **Date**: Set a specific date and time for the process to start
2. **Cycle**: Configure a recurring schedule, either as an ISO 8601 repeating interval or as a Spring cron expression (select **ISO** or **Cron** next to the **Definition** label)

A Timer Start Event offers only these two timer types. **Duration** is available on intermediate and boundary timer events, not on start events.

> [!WARNING]
>
> Starting processes through registered timers requires sending a process start message to Kafka, which needs a service account and authentication. See [Service Accounts](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution.md#scheduler-service-account) for details.

For more detailed information about Timer Start Events, refer to the [Start Timer Event](https://docs.flowx.ai/6.x/docs/building-blocks/node/timer-events/timer-start-event.md) 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.

**1. 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')

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

Correlation Data Configuration

4. Configure the message correlation in the node properties:

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

Message Correlation Configuration

**2. 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')
   * A **Process Key** where the message data is stored in the started process

> [!NOTE]
>
> A Message Start Event has no **Correlation Key** field. The correlation value set on the throw event must not be empty, and the receiver process doesn't start again while an instance started with the same message name and correlation value is still active.

**3. Test the Configuration**

Run the sender process and watch as it automatically triggers the receiver process when the Message Throw Event is reached.

![Message Start Event in Action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_with_message_event.gif)

Message Start Event in Action

> [!NOTE]
>
> 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).

## Email and webhook triggers

A Message Start Event can also start a process directly from external events, without any Kafka configuration or sender process. Set the node's **Trigger Type** to one of these options and select a data source configured in Integration Designer:

* **Email Trigger**: starts a process instance when an email arrives in a monitored inbox (IMAP). The email data (sender, subject, body, attachments) is automatically mapped to the process instance data. Microsoft Outlook mailboxes use the same **Email Trigger** option: select a Microsoft Outlook data source with **Read** or **Read & Send** scope in the **Select Email Trigger** dropdown. The email arrives via the MS Graph API.
* **Incoming Webhook**: starts a process instance from an external HTTP POST request. The request payload (body, headers, timestamp) is automatically mapped to the process instance data.

**1. Create the Data Source**

In your project, go to **Integrations** → **Data Sources** and create the trigger resource: an [Email Trigger](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/email-trigger.md), a [Microsoft Outlook](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/microsoft-outlook-data-source.md) data source, or an [Incoming Webhook](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/incoming-webhooks.md).

**2. Configure the Message Start Event**

1. Add a **Message Start Event** node as the starting point of your process
2. Set the **Trigger Type** to **Email Trigger** (for IMAP or Microsoft Outlook data sources) or **Incoming Webhook**
3. Select the data source created in the previous step

**3. Use the Incoming Data**

The trigger payload is mapped to the process instance data automatically, so you can reference the email fields or webhook body in your process logic.

For the full configuration reference of each trigger type, see the [Message Start Event](https://docs.flowx.ai/6.x/docs/building-blocks/node/message-events/message-catch-start-event.md) documentation.

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

## Next steps

After setting up your process initiation methods, you can:

> [card] [Configure Process Data Models](https://docs.flowx.ai/6.x/docs/building-blocks/process/data-model.md)
>
> Define the data structure for your process instances

> [card] [Set Up User Interfaces](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/creating-a-user-interface.md)
>
> Create user interfaces for human-interactive processes

> [card] [Implement Business Rules](https://docs.flowx.ai/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action.md)
>
> Add decision logic to your processes

> [card] [Configure Integrations](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)
>
> Connect your processes to external systems


## Related topics

- [Finding identifiers and parameters](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/finding-identifiers-and-parameters.md)
- [Process instance](https://docs.flowx.ai/6.x/docs/projects/runtime/active-process/process-instance.md)
- [Configuring access roles for processes](https://docs.flowx.ai/6.x/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes.md)
- [React Native SDK](https://docs.flowx.ai/6.x/sdks/react-native-renderer.md)
- [Renderer SDKs](https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.