> ## 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.
# Subprocess management
> 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
**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.
***
## Configuring & starting subprocesses
Design subprocesses within the FlowX.AI Designer, mirroring the main process structure.
* Within user tasks or task nodes.
* Custom node type in the main process.
* Using the corresponding node.
### Parameter inheritance
Available for **Start Subprocess** action and **Call Activity** node.
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.
## 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
Academy course covering embedded/call activities, UI updates, and data passing patterns
**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.