# Call a flow

import { Steps } from "@astrojs/starlight/components"

**Call a flow** is a Studio step that runs another flow in your organization. You pass parameters into that flow’s
**Flowhook** trigger. By default (**Wait for completion**), the parent waits until the called flow finishes and you can use
the values it returns from **Success**. Choose **Run in background** when you only need to start the called flow and continue
the parent right away, without using its output.

## When to use

- Several parent flows need the same reusable sequence, such as formatting an employee record or looking up a user.
- You want a typed contract between flows (required fields, returned properties) without exposing an HTTP URL.
- You need to start a long called flow (for example an approval) and continue without waiting for it to finish — use
  **Run in background**.
- Prefer [Run flow through webhook](../trigger-your-flow/run-flow-through-webhook/) when an **external** system must
  start the flow over HTTPS.
- Prefer [Use AI··Agent](../../use-ai-in-flows/use-ai-agent/) when an AI··Task should decide whether to call the other
  flow.

Before you begin, you need permission to create and deploy flows in the environment. Build the called flow first, then
open the parent flow in the same environment.

## Guide

### Add a Flowhook trigger

A **Flowhook** trigger is the contract that makes a flow callable. Other flows can pass only the properties you define
here. A flow with only a webhook, emailhook, or scheduler trigger does not appear in the Call a flow picker.

<ol>
<li>

**Create the called flow.** Name it for the job it performs, then open it in the designer.

</li>
<li>

**Add Flowhook.** Open **Add a step**, choose **Triggers**, then **Flowhook**. Rename the step and fill a description.

</li>
<li>

**Open Settings.** On the Flowhook step, open the **Settings** tab. The schema root is an **Object**. Use **Add a
property** for each value the parent must send.

</li>
<li>

**Define each property.** Set **Title**, **Description**, and **Property type** (**String**, **Number**,
**Boolean**, **Object**, or **Array**). Turn **Required** on for fields the parent must always send.

<div class="docs-screenshot-compact">

![Called flow Format employee display name: Flowhook step Receive employee names with Settings showing required First name and Last name string properties and a Department string](./assets/flowhook-schema.png)

</div>

</li>
</ol>
### Define the flow output

The flow **Output** tab lists the properties a **Success** step can return to the parent. Define this before you map
values on Success, or the Success form has nothing to fill.

<ol>
<li>

**Open the flow inspector.** In the designer toolbar, open the settings control, then choose **Output**.

</li>
<li>

**Add returned properties.** Use **Add a property** for each value the parent should read. Set **Title**,
**Description**, and **Property type**.

<div class="docs-screenshot-compact">

![Flow inspector Output tab titled Flow output definition with Full name and Department string properties](./assets/flow-output.png)

</div>

</li>
</ol>
### Return results with Success

A **Success** step ends the called flow as successful and assigns the output properties you defined. The parent reads
those values after Call a flow finishes.

<ol>
<li>

**Add Success.** After the last working step (or directly after the Flowhook if the flow only shapes the payload),
add **Success** from the **Flow** category. Rename the step.

</li>
<li>

**Open Output.** On the Success step, open the **Output** tab. Each property from the flow output can be assigned
here. If a property is missing, open **Advanced** and turn it on.

</li>
<li>

**Map each property.** Fill the fields from earlier steps (for example the Flowhook parameters) using the data
picker, or type a sample value.

<div class="docs-screenshot-compact">

![Success step Return display name Output tab with Full name set to Alex Martin and Department set to Finance](./assets/success-output.png)

</div>

</li>
<li>

**Deploy the called flow.** Deploy it to the environment where the parent will run. Call a flow lists flows that
are deployed in the current environment by default. See
[Manage version and deployments](../../../operate/manage-version-and-deployments/).

</li>
</ol>
### Call a flow

**Call a flow** selects a deployed, Flowhook-enabled flow, a version, and the parameters to send.

<ol>
<li>

**Add Call a flow.** In the parent flow, open **Add a step**, choose **Flow**, then **Call a flow**.

</li>
<li>

**Select a flow.** Open **Input**. Choose **Select a flow**. The list defaults to **Deployed in this environment**.
Switch to **Deployed in all environments** only when you need a flow that is not deployed in the current
environment. Search, then pick the called flow.

<div class="docs-screenshot-compact">

![Select a flow wizard filtered to Deployed in this environment, listing Format employee display name](./assets/select-a-flow.png)

</div>

</li>
<li>

**Pick a version.** Choose a version of that flow. The **Latest** badge marks the most recent version. Prefer
**Latest** while you iterate; pick a named version when the parent must stay on a frozen snapshot.

<div class="docs-screenshot-compact">

![Pick a version list for Format employee display name with the Latest badge on the current version](./assets/pick-a-version.png)

</div>

</li>
<li>

**Fill Parameters.** After you pick a version, Studio copies the flow name and description onto the step and shows
the Flowhook properties as **Parameters**. Fill every required field. Map values from earlier parent steps, or type
sample values. If an optional property is missing, open **Advanced** and turn it on.

<div class="docs-screenshot-compact">

![Handle leaver request designer: Call a flow step Format employee display name with Input parameters First name Alex, Last name Martin, and Department Finance](./assets/call-a-flow-parameters.png)

</div>

</li>
</ol>
If the selected version has no Flowhook step, Studio shows that the flow version is not callable. Add a Flowhook on
that flow, deploy it, then pick the version again.

### Choose Wait for completion or Run in background

**Execution mode** on the Call a flow **Settings** tab controls whether the parent waits for the called flow.

| Mode                              | What the parent does                        | Called flow output       | On failure |
| --------------------------------- | ------------------------------------------- | ------------------------ | ---------- |
| **Wait for completion** (default) | Pauses until the called flow finishes       | Available in data picker | Shown      |
| **Run in background**             | Continues as soon as the called flow starts | Not available            | Hidden     |

<ol>
<li>

**Open Settings.** On the Call a flow step, open the **Settings** tab. **Execution mode** defaults to **Wait for
completion**.

</li>
<li>

**Choose Run in background when the parent should not wait.** Set **Execution mode** to **Run in background**.

<div class="docs-screenshot-compact">

![Handle leaver request: Call a flow step Format employee display name Settings tab with Execution mode set to Run in background and the no-output callout](./assets/execution-mode.png)

</div>

</li>
</ol>
### Choose what happens when the called flow fails

**On failure** controls whether the parent stops or continues when the called flow fails. If the called flow cannot be
started, the Call a flow step fails in both modes.

<ol>
<li>

**Open Settings.** On the Call a flow step, open the **Settings** tab.

</li>
<li>

**Set On failure.** **Stop execution** (the default) fails the parent when the called flow fails. **Continue
execution** lets later parent steps run so you can branch on the error.

<div class="docs-screenshot-compact">

![Handle leaver request: Call a flow step Format employee display name Settings tab with On failure set to Stop execution](./assets/on-failure.png)

</div>

</li>
</ol>
### Use the called flow’s result

After a successful **Wait for completion** call, later parent steps can pick properties from the Call a flow step in the
data picker. Those properties match the called flow’s output.

1. **Add the next parent step.** Add the step that should consume the result (for example **Transform data** or an
   integration).
2. **Pick from Call a flow.** In a formula field, open the data picker, choose the Call a flow step, then select the
   output property you need.
3. **Inspect a run.** After you run the parent, open **Logs** on the Call a flow step. **Request** shows
   the parameters that were sent. **Response** shows the output or the error.

## Example

An IT operator automates offboarding. The parent flow **Handle leaver request** calls **Format employee display name**
so every leaver flow builds the same display name.

On **Format employee display name**, the Flowhook **Receive employee names** requires **First name** and **Last name**,
and accepts **Department**. Flow output defines **Full name** and **Department**. The Success step **Return display
name** returns **Full name** `Alex Martin` and **Department** `Finance`.

On **Handle leaver request**, Call a flow targets **Format employee display name** at **Latest**, with **First name**
`Alex`, **Last name** `Martin`, and **Department** `Finance`. **On failure** is **Stop execution**. Later parent steps
read **Full name** and **Department** from the Call a flow step. After a run, **Response** shows those
same values.

In production, the called flow would usually query your identity directory using the same Flowhook contract. This
example keeps the contract and the call, without that extra integration.

## Keep in mind

- Only flows that start with a **Flowhook** trigger appear in the picker. A webhook URL is for external callers, not
  for flow-to-flow calls.
- The picker hides the flow you are editing, so a flow cannot call itself.
- Default scope is **Deployed in this environment**. If the called flow is missing from the list, deploy it or switch
  the scope.
- If you change the Flowhook schema or the flow output, deploy the called flow again and re-check the parent’s
  **Parameters** and data picks.

## Related

[End a flow with Success or Failure](../end-a-flow-with-success-or-failure/) ·
[Trigger your flow](../trigger-your-flow/) ·
[Run flow through webhook](../trigger-your-flow/run-flow-through-webhook/) ·
[Manage version and deployments](../../../operate/manage-version-and-deployments/)