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

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

> [!NOTE]
>
> 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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps.md).

***

## 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 key name**: 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](https://docs.flowx.ai/6.x/docs/building-blocks/process/data-mappers.md) |
| Call an integration workflow (REST, DB, AI ops) and capture the result | Send Message Task with **Start Integration Workflow** action | Mapped into process variables by the **Receive Message Task** that waits for the workflow | [Start Integration Workflow](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md) |
| 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](https://docs.flowx.ai/6.x/ai-platform/using-agents/bpmn-integration.md) |
| Compute or transform values inline | Business Rule action | Writes to keys passed to `output.put(key, value)` | [Business rule action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action.md) |

***

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

**1. Add a Send Message Task**

Configure it with the **Start Integration Workflow** action: select the workflow and map its input. The action has no output setting; the output is configured on the next node.

**2. Add a Receive Message Task immediately after**

The process pauses on this node until the workflow completes. In its **Data Stream** configuration, set the source to **Workflow** and select the workflow. Then 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**.

**3. Read the result downstream**

Any node after the Receive Message Task, including gateway, business rule, and user task, can read the mapped output from process variables.

For the full configuration walkthrough, see [Start Integration Workflow → Receiving output](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md#receiving-output) and [Send/Receive Message Task nodes](https://docs.flowx.ai/6.x/docs/building-blocks/node/message-send-received-task-node.md).

> [!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](https://docs.flowx.ai/6.x/ai-platform/using-agents/bpmn-integration.md).

***

## 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: select `customer.id` as the source path in **Input Mapping**, or write `${customer.id}` with **Legacy mapping** turned on (see [Start Integration Workflow → Input mapping](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md#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](https://docs.flowx.ai/6.x/docs/building-blocks/process/data-mappers.md)).
* **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](https://docs.flowx.ai/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action.md).
* **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]
>
> Placeholders in an action's JSON message, such as a Start Integration Workflow message, name process data paths from the root of the process data, with no prefix: `${customer.id}`. A `${processInstanceData.customer.id}` placeholder resolves to nothing at runtime. Subprocess Data Mappers use `${variableName}`. Always follow the syntax shown on the destination page.

***

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

**1. User uploads document on a user task**

The file id lands on process variables, for example at `loan.documentId`.

**2. Send Message Task triggers a credit-check integration workflow**

Input mapping reads `loan.customerId`.

**3. Receive Message Task waits for the workflow**

Its data stream maps the workflow output to `creditCheck`. When the workflow completes, the response lands there in process variables.

**4. Service Task calls the document-extraction agent**

Input mapping sends `loan.documentId`. Output mapping writes the extracted fields to `loan.extracted`.

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

***

## Common pitfalls

> [accordion] Reading a workflow result before the Receive Message Task
>
> The workflow output only reaches process variables after the Receive Message Task unblocks. A node placed between Send and Receive will see an empty value.

> [accordion] Output key collision
>
> Two integrations whose output maps to the same key will overwrite each other. Use distinct, descriptive paths (`creditCheck`, `addressVerification`) instead of generic ones (`result`, `data`).

> [accordion] Wrong placeholder prefix
>
> `${processInstanceData.customer.id}` resolves to nothing at runtime: placeholders in an action's JSON message read process data from its root, so write `${customer.id}`. Subprocess Data Mappers use `${variableName}`. Follow the syntax shown on each node's page.

> [accordion] Expecting a synchronous result back to an external HTTP caller
>
> 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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps.md).

***

## Related resources

> [card] [Data mappers](https://docs.flowx.ai/6.x/docs/building-blocks/process/data-mappers.md)
>
> Parent ↔ subprocess parameter mapping

> [card] [Start Integration Workflow](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md)
>
> Workflow input/output and the Receive Message Task pattern

> [card] [BPMN integration with agents](https://docs.flowx.ai/6.x/ai-platform/using-agents/bpmn-integration.md)
>
> Calling AI agents from a process

> [card] [Business rule action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action.md)
>
> Inline scripts that read from `input` and write to `output`

> [card] [Send/Receive Message Task](https://docs.flowx.ai/6.x/docs/building-blocks/node/message-send-received-task-node.md)
>
> Node-level configuration of the wait pattern

> [card] [Consuming FlowX from external apps](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps.md)
>
> External HTTP/SDK integration patterns


## Related topics

- [BPMN integration](https://docs.flowx.ai/6.x/ai-platform/using-agents/bpmn-integration.md)
- [Start integration workflow action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md)
- [Using Knowledge Base in workflows](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows.md)
- [FlowX.AI 5.0.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025.md)
- [Subprocess management](https://docs.flowx.ai/6.x/docs/building-blocks/process/subprocess.md)


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