# Map items

Map Items transforms every item in a list into a new object. Use it to select fields, rename them, add calculated values, convert types, or prepare records for an API, CSV file, email, or database.

## When to use it

Use Map Items when the input is a **list** and every item must follow the same output structure.

Input:

```json
[
  { "first_name": "Awa", "score": "85", "debug": true },
  { "first_name": "Moussa", "score": "42", "debug": false }
]
```

Possible output:

```json
[
  { "name": "Awa", "score": 85, "position": 1 },
  { "name": "Moussa", "score": 42, "position": 2 }
]
```

## Configuration

### Input context key

Select the list to transform, for example `{state.customers}`, `{input.items}`, or an upstream node output. The field supports autocomplete.

### Keep original item fields

- **Disabled:** each output item starts empty and contains only the fields defined in the visual editor.
- **Enabled:** the original fields are retained, then the configured fields are added or replaced.

### Output fields

Add fields with the visual editor. Each row contains:

- **Output field:** name or nested path to create, such as `name` or `customer.email`.
- **Value:** defines a fixed value or a template and can convert it to Text, Number, Boolean, or JSON.
- **Copy from:** copies an existing value while preserving its original type.

Examples:

- Copy `{item.first_name}` into `name`.
- Use `{item.score}` as a Number in `score`.
- Use the fixed text `processed` in `status`.

## Variables available for each item

- `{item}`: the complete item currently being transformed.
- `{item.first_name}`: a field of the current item.
- `{item_index}`: zero-based position: `0`, `1`, `2`, and so on.
- `{item_number}`: one-based position: `1`, `2`, `3`, and so on.

`{item_number}` is useful for a human-readable row number, display order, or position. It is optional.

## Map Items versus Set Fields

- **Map Items** always expects a list and is intended to build the same output structure for every item.
- **Set Fields** accepts one object or a list and is intended to enrich, rename, or remove fields from existing data.

## Runtime output

The mapped list is written to `last_output` and `last_output_parsed`. Downstream nodes can use:

```text
{outputs.<node_id>.parsed}
```

To read the first mapped item:

```text
{outputs.<node_id>.parsed.0}
```

## Example workflow

Use the workflow card below to create a working example. The sample customer list is already loaded by Set State; run it and inspect the Map Items output.

---

*Source: https://agentbuilder.systalink.sn/docs/node-map-items — human documentation.*
*Other language: [/docs-md/fr/node-map-items.md](/docs-md/fr/node-map-items.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*