# Use Mindflow built-in variables

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

Mindflow exposes a reserved **`Mindflow`** variable with run context your flow can read in formulas and data picks:
environment and flow names, run IDs, who started the run, and related timestamps. You do not declare this variable under
flow **Variables** — Studio injects it automatically.

## When to use

- You need the current environment name, flow name, or who started the run inside a step without hard-coding values.
- You want the flow run ID in HTTP requests, transforms, or notifications.
- Prefer [global flow variables](./transform-data-and-reassign-variables/) when you control the name and initial value
  yourself. Prefer [Platform Artifacts](./store-data-with-platform-artifacts/) when data must persist across runs.

Before you begin, open a flow in the designer with permission to edit it.

## Guide

### Open built-in variables in the data picker

Built-in variables live under **Built-in variables → Mindflow** in the data picker, grouped by Environment, Flow, Step,
and more. Each field inserts a path such as `Mindflow.environmentName`.

1. **Open a step inspector.** Select a step that accepts formulas or data picks (for example **Transform data** or an
   HTTP step field).
2. **Open the data picker.** Choose **/** or the data-pick control on the field you want to fill.
3. **Choose a built-in field.** Open **Built-in variables → Mindflow**, then a group (for example **Environment**), and
   select the label you need (for example **Environment name**). Studio inserts a pill such as
   `Mindflow.environmentName`.

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

   ![Data picker open on Built-in variables Mindflow with environment, flow, and user fields](./assets/built-in-variables-data-picker.png)

   </div>

### Understand designer previews versus runtime values

In the designer, stable fields such as **Environment name** and **Flow name** preview from your current organization,
environment, and flow. Fields that only exist during a real run or dry-run show **`[runtime-only]`** instead of an
empty value — for example **Flow run ID**. That placeholder means the value appears when you dry-run a step or run the
full flow.

1. **Preview a stable field.** On a **Transform data** step, add a variable bound to **Environment name**. The preview
   shows your environment’s display name.
2. **Preview a run-scoped field.** Add another variable bound to **Flow run ID**. The preview shows `[runtime-only]`.
3. **Dry-run or run the flow.** Dry-run the step or run the flow; the same pills resolve to real values.

### Reference: built-in fields

Use path syntax `Mindflow.<field>` in formulas. Studio exposes names, timestamps, and run IDs — not internal entity
IDs.

#### Environment

| Field (path suffix) | Designer preview    | At dry-run / run |
| ------------------- | ------------------- | ---------------- |
| `environmentName`   | Current environment | Same             |

#### Flow

| Field (path suffix) | Designer preview    | At dry-run / run    |
| ------------------- | ------------------- | ------------------- |
| `flowRunId`         | `[runtime-only]`    | Current flow run ID |
| `flowName`          | Current flow        | Same                |
| `flowUrl`           | Studio designer URL | Same                |

#### Step

| Field (path suffix) | Designer preview | At dry-run / run          |
| ------------------- | ---------------- | ------------------------- |
| `stepName`          | `[runtime-only]` | Current step display name |

#### User

| Field (path suffix) | Designer preview | At dry-run / run                                    |
| ------------------- | ---------------- | --------------------------------------------------- |
| `userEmail`         | Current user     | Email of who started the run, when available        |
| `username`          | Current user     | Display name of who started the run, when available |

#### Trigger

| Field (path suffix) | Designer preview | At dry-run / run                           |
| ------------------- | ---------------- | ------------------------------------------ |
| `triggerType`       | `MANUAL`         | How the flow was triggered                 |
| `triggeredAt`       | Designer default | When the run was triggered (ISO timestamp) |

#### Organization

| Field (path suffix) | Designer preview     | At dry-run / run |
| ------------------- | -------------------- | ---------------- |
| `orgName`           | Current organization | Same             |

#### Parent flow

| Field (path suffix) | Designer preview | At dry-run / run                               |
| ------------------- | ---------------- | ---------------------------------------------- |
| `parentFlowName`    | `[runtime-only]` | Parent flow name when invoked as a nested flow |
| `parentFlowRunId`   | `[runtime-only]` | Parent run ID when invoked as a nested flow    |

## Example

This example tags an HTTP request with the environment name and shows how run-scoped fields behave.

1. **Create a flow** with a **Transform data** step and an HTTP step that sends a test request.
2. **Bind environment name.** On **Transform data**, add variable `environmentName` from **Built-in variables →
   Mindflow → Environment name**. Confirm the preview matches your environment.
3. **Bind flow run ID.** Add variable `runId` from **Built-in variables → Mindflow → Flow run ID**. Confirm the preview
   is `[runtime-only]`.
4. **Dry-run the HTTP step** with `Mindflow.environmentName` in a query parameter. The inspect result shows your
   environment name.
5. **Run the flow.** After the run completes, the same parameter resolves to the live environment name; `runId` shows
   the actual flow run ID if you mapped it on the HTTP step.

## Keep in mind

- You cannot rename or delete the **`Mindflow`** variable. User-defined variables cannot use that name.
- **`[runtime-only]`** is a designer preview only — it is not sent to external systems at runtime.
- **User** fields depend on the principal that started the run; automated triggers may leave them empty.
- **Parent flow** fields are filled only when the run is started as a nested flow.

## Related

- [Transform data and reassign variables](./transform-data-and-reassign-variables/)
- [Work with data overview](./)