# Mapping or Transforming Data

> Choose the smallest data operation that fits: map a value, transform it in place, parse structure, reshape a list, use AI, or write code.

Mapping passes an existing value into another field. Transforming changes its shape or content first. Start with mapping, then add the smallest transformation that makes the receiving step accept the data.

## Choose by what must change

| What you need                                                | Use                                                                 | Why                                                                                     |
| ------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Put an existing value into a field unchanged                 | **Mapping**                                                         | No extra step or operation is needed.                                                   |
| Clean, calculate, format, or take part of one value          | **[Data Transformation](/build/core-concepts/data-transformation)** | The change stays beside the field that needs it and does not add a canvas step.         |
| Turn JSON text into selectable fields                        | **[Parse JSON](/build/action-steps/parse-json)**                    | It exposes the structure so later steps can map each field.                             |
| Filter, sort, limit, deduplicate, combine, or process a list | **List steps**                                                      | The list itself is the unit of work, and the result can be inspected and reused.        |
| Extract meaning from inconsistent, unstructured text         | **[AI Data Transform](/build/ai-features/ai-transform)**            | Plain-language instructions handle text whose layout changes from one item to the next. |
| Apply bespoke calculations, reshaping, or business rules     | **[Code editor](/build/action-steps/code-execution)**               | Python covers logic that the visual operations do not express clearly.                  |

## Map when the value already fits

Click the data icon beside the destination field and pick the value from **Data select**. Glow inserts a reference to the earlier step, such as:

```text
{{ 2.ret.email }}
```

The path depends on the step that produced the value. App actions usually place their answer under `ret`; triggers and Glow flow steps often expose fields at the top level. Pick from the data panel instead of guessing the path.

Mapping can sit inside surrounding text when the destination expects text:

```text
Order {{ 2.ret.order_id }} is ready for collection.
```

Keep mapping when the source type and format already match the destination. Adding a separate step to rename nothing or copy one value makes the canvas harder to read without changing the result.

## Keep routine changes in Data Transformation

**Data Transformation is the default for changing one mapped value.** Use it for trimming text, changing capitalisation, extracting a domain, calculating a price, formatting a date, taking an item from a list, or supplying a fallback.

Open the field's data icon, switch to **Data transformation**, and add operations to the mapped value. Glow applies them from left to right when that field is resolved. The earlier step's output remains unchanged, so another field can still use the original value.

You can also write the same chain inside the placeholder:

```text
{{ 2.ret.email | trim | lower }}
{{ 3.subtotal | times:1.21 | number_format:2:sep_comma_dot }}
{{ 4.company | default:"Unknown" }}
```

| Chain                                             | Result                                                                                   |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `trim` then `lower`                               | Removes outer spaces, then makes the text lowercase.                                     |
| `times:1.21` then `number_format:2:sep_comma_dot` | Multiplies the number, then returns text such as `1,210.00`.                             |
| `default:"Unknown"`                               | Replaces a missing, null, empty, or whitespace-only value; it preserves `0` and `false`. |

A pipe belongs **inside** the braces. Operations run in the order written, so calculate before formatting a number as text.

> Prefer the visual **Data transformation** tab for day-to-day work. It offers
> operations that fit the current value and writes the pipe chain for you. The
> inline form is useful when reviewing, copying, or troubleshooting a field.

### Data Transformation can reshape a list inside one field

A list does not always need another canvas step. If one destination field needs a simple derivative, keep it local:

```text
{{ 3.results | sort:ascending:name | pluck:email | join:comma_space }}
```

That chain sorts records by `name`, takes each record's `email`, and joins the addresses into text. Use this approach when only that field needs the result.

Use a list step instead when the changed list should be visible in the execution history, reused by several later steps, split into routes, or processed item by item.

## Parse structure before mapping fields

Use **Parse JSON** when a value is text that contains JSON. Mapping can select the whole string, but it cannot select fields hidden inside that string.

Given this text:

```json
{ "customer": { "email": "ada@example.com" }, "total": 125 }
```

Map the text into a Parse JSON step. If Parse JSON is step 4, later steps can read:

```text
{{ 4.customer.email }}
{{ 4.total }}
```

Use dots for nested records and list positions: `{{ 4.items.0.sku }}` is valid; `{{ 4.items[0].sku }}` is not.

Do not add Parse JSON when the data picker already exposes the fields. In that case the value is structured already, so map it directly.

## Use list steps when the list is the result

Dedicated list steps make a changed collection available to the rest of the workflow:

| Need                                                   | Step                                                                 |
| ------------------------------------------------------ | -------------------------------------------------------------------- |
| Keep only matching items and route the rest separately | **[Filter](/build/action-steps/filter-items)**                       |
| Put records in order, including tie-breaking rules     | **[Sort](/build/action-steps/sort)**                                 |
| Keep the first or last number of items                 | **[Limit](/build/action-steps/limit)**                               |
| Keep one copy of repeated values or records            | **[Remove duplicates](/build/action-steps/remove-duplicates)**       |
| Append two lists or match records by shared fields     | **[Combine](/build/action-steps/combine)**                           |
| Run one action for every item                          | **[Run for Each Item](/build/action-steps/loops/run-for-each-item)** |
| Run several steps for every item                       | **[Repeater](/build/action-steps/loops/repeater)**                   |

List steps return a result you can inspect after a run. That makes them the clearer choice when the transformation is an important stage of the workflow rather than formatting for one destination field.

## Use AI only when rules cannot find the value reliably

**AI Data Transform** suits emails, receipts, transcripts, and other text whose wording or position changes. Write one instruction per value you need, up to three:

> Extract the purchase order number from `{{ 2.ret.body }}`.

If AI Data Transform is step 5, its answers are positional:

```text
{{ 5.result.0 }}
{{ 5.result.1 }}
{{ 5.result.2 }}
```

Reordering instructions changes what those references mean. For stable JSON, delimiters, dates, or arithmetic, use Parse JSON, Data Transformation, or a list step instead. Deterministic operations are easier to test and do not depend on model interpretation.

## Use Code editor for rules, not routine formatting

Choose **Code editor** when several values interact, the output needs a bespoke structure, or the rule is clearer as Python than as a long chain of visual operations.

References in Python must stand alone and remain unquoted:

```python filename="main.py"
import json

orders = {{ 3.results }}
tax_rate = {{ $var.TAX_RATE }}

total = sum(order["amount"] for order in orders)
print(json.dumps({"total_with_tax": round(total * tax_rate, 2)}))
```

The printed value is text under:

```text
{{ 4.result.executionOutput }}
```

To map fields from the printed JSON, follow Code editor with Parse JSON. Use Data Transformation instead for a short chain on one value; it keeps the intent visible beside the destination field.

## A practical order of preference

1. **Map it** if the value already fits.
2. **Use Data Transformation** if one field needs a deterministic change.
3. **Add Parse JSON or a list step** if the workflow needs a new reusable structure.
4. **Use AI Data Transform** for meaning hidden in inconsistent text.
5. **Use Code editor** when the rule genuinely needs code.

This order keeps simple workflows short without forcing complex work into an unreadable field.

## What's Next?

- 👉 **[Data Transformation →](/build/core-concepts/data-transformation)**: browse the complete operation catalogue and configure chains visually.
- Decide where persistent and run-scoped values belong in [Where Data Lives](/manage/workspace-settings/where-data-lives).
- Check output wrappers, nested paths and system references in [Variable Reference Syntax](/reference/variable-syntax).