> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/map-variables-and-expressions.md).

# Map variables and expressions

Variables and expressions pass data between workflow nodes. Use a reference when a value must come from the current run. Use fixed text when the value should remain the same.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fx2e8VVzbKO7y7JGlJu4o%2FG022.mp4?alt=media&token=1a30d604-2a6b-4d06-ac88-7d32e26adb4c>" %}

## Before you start

Complete [First input to output workflow](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/first-input-to-output-workflow.md) and run the node whose result you want to use. A field is a named value, similar to a column heading. An object groups named fields; an array is a list of items. Unlike a value copied from a spreadsheet cell, a reference reads the current run’s value.

## Inspect the source data

Run the source node and inspect its structured result.

![Structured source-node result](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/aCFZ6uUyVOg8wd2AZDZV/assets/g022-g022-01-canvas.png)

Identify the exact field names and list structure before writing an expression.

## Insert a reference

Open **Output → Edit Template**. In the template editor, use the reference picker to select the source node and the field you need. Where the editor offers an inline reference menu, type `@` to open it. Select the inserted reference to open its **Expression** editor. Run the source node first if its result fields are not yet available.

![Source reference in an Output template](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/Ki2N6RO8BAR11pFcS69f/assets/g022-g022-02-template.png)

A live reference uses the latest result rather than a copied value.

## Select or transform values

Open the reference's Expression editor to select or transform fields.

![Expression editor and field selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/0JOmvR3EHmhZaEj4iWIo/assets/g022-g022-03-expression.png)

Use the available property suggestions to build paths, filter list items, or calculate totals from the actual result structure.

## Read a simple field path

Suppose the selected source returns this object:

```json
{"items": [{"amount": 12}, {"amount": 8}]}
```

Expand **items**, the first list item, and **amount** in the results picker. The path after the source reference is `items[0].amount`, and the value is `12`. List positions start at `0`. Selecting the second item gives `items[1].amount`, whose value is `8`. Keep the source identifier inserted by the picker; the path prefix depends on the node and its returned fields.

In the JMESPath expression editor, `sum` adds a list of numbers. For this data, applying `sum` to the selected `items[].amount` path gives `20`. Build the full path from your actual source reference rather than typing a node name as plain text. Check the preview or a new run before using a calculated value downstream.

If your source returns text containing JSON instead of fields you can expand, configure a [structured output](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/structured-outputs-and-templates.md) before mapping its properties.

## Check the mapped result

Run the workflow again and compare the selected fields with the source result.

![Mapped output values compared with the source](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/XUhT9orDaOov9z08mabj/assets/g022-g022-04-result.png)

Check both the individual values and any calculated total.

## Important behavior

Choose a reference that matches the value you need. Text, numbers, lists, files, and objects are different data types.

If a reference fails, compare its field path with the source node’s output.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/workflow-builder/map-variables-and-expressions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
