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

# Start integration workflow action

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

> [!NOTE]
>
> The Start Integration Workflow action is available on **Send Message Task**, **Task**, and **User Task** nodes within BPMN processes.

## Overview

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

> [!TIP]
>
> For triggering workflows from **UI Flows** (without a BPMN process), see the [Start Workflow action](https://docs.flowx.ai/6.x/docs/building-blocks/ui-flows.md#configuring-the-start-workflow-action).

***

## How it works

When a Start Integration Workflow action is triggered:

**1. Input data is sent**

The input data mapped in the action configuration is sent as start variables to the workflow.

**2. Workflow executes**

The integration workflow runs with the provided inputs, executing its configured nodes (REST calls, data transformations, AI operations, etc.).

**3. Output is captured**

Workflow output data is captured in the process instance upon completion, at the location configured on the Receive Message Task's Data Stream.

**4. Process continues**

The BPMN process continues to the next node after the workflow completes.

> [!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. When the action runs on a User Task, the User Task's own data stream can receive the output instead - see [Receiving output](#receiving-output).

### How do the process and the workflow communicate?

Over Kafka. You don't add a Kafka action or pick a topic: each workflow gets its own pair of topics, named after the workflow's ID.

| Direction | Default topic | Who listens |
| - | - | - |
| Process → workflow: the start message, with the mapped input | `ai.flowx.integration.receive.<workflow-id>.in` | Integration Designer, on `ai.flowx.integration.receive.*` |
| Workflow → process: the workflow output | `ai.flowx.engine.receive.<workflow-id>.out` | Process Engine, on `ai.flowx.engine.receive.*` |

The Receive Message Task picks up the output from the second topic. To change the topic patterns or let Integration Designer create these topics automatically, see the [Integration Designer setup guide](https://docs.flowx.ai/6.x/setup-guides/integration-designer-setup.md#engine-and-integration-communication-topics).

***

## Configuration

### Selecting a workflow

The workflow search field (**Search workflow by name**) displays:

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

### Input mapping

Map process variables to workflow input parameters. By default the action uses data mappers: open **Input Mapping** and map each workflow input to a process data attribute selected as a source path, for example `customer.id` to `customerId`.

> [!WARNING]
>
> In a data mapper, a `${...}` typed as a static value resolves only against project configuration parameters. To send process data, select it as a source path: a typed `${customer.id}` reaches the workflow as literal text.

With **Legacy mapping** turned on, the input is a JSON template. Placeholders name process data paths from the root of the process data, with no prefix:

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

### Receiving output

To capture workflow output in your process:

1. Add a **Receive Message Task** node after the node with the Start Integration Workflow action
2. In its **Data Stream** configuration, set the source to **Workflow** and select the workflow
3. Choose where the output lands: map each End node's output with **Output Mapping** (the default), or turn on **Legacy Mapping** and set a single **Key Name**
4. Subsequent nodes can access the output data at the mapped keys

When the action runs on a **User Task**, you can configure the same data stream in the User Task's **Integration Output** instead, and the token stays on the User Task. The output lands in process data, but a screen that is already open doesn't refresh when it arrives. To show a workflow's result on the screen, see [Start a workflow from a User Task and show the result](https://docs.flowx.ai/6.x/cookbooks/start-workflow-from-user-task.md).

***

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

> [card] [Build your first workflow](https://docs.flowx.ai/6.x/docs/getting-started/building-your-first-workflow.md)
>
> Tutorial: call a REST API from a workflow and start it from a process

> [card] [Passing data between nodes](https://docs.flowx.ai/6.x/docs/building-blocks/process/passing-data-between-nodes.md)
>
> How node outputs land in process variables and how downstream nodes read them

> [card] [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)
>
> Build and configure integration workflows

> [card] [UI Flows - Start Workflow](https://docs.flowx.ai/6.x/docs/building-blocks/ui-flows.md#configuring-the-start-workflow-action)
>
> Trigger workflows from UI Flows without BPMN processes

> [card] [Message Events](https://docs.flowx.ai/6.x/docs/building-blocks/node/message-events/message-events.md)
>
> Learn about Send and Receive Message Task nodes

> [card] [Actions Overview](https://docs.flowx.ai/6.x/docs/building-blocks/actions/actions.md)
>
> Explore all available action types


## Related topics

- [BPMN integration](https://docs.flowx.ai/6.x/ai-platform/using-agents/bpmn-integration.md)
- [Workflow data model](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/workflow-data-models.md)
- [Combine UI Flows, processes, and workflows](https://docs.flowx.ai/6.x/docs/building-blocks/combining-ui-flows-processes-and-workflows.md)
- [Start a workflow from a User Task and show the result](https://docs.flowx.ai/6.x/cookbooks/start-workflow-from-user-task.md)
- [Chat-driven workflows](https://docs.flowx.ai/6.x/ai-platform/chat-driven-workflows.md)


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