Map fields
Reshape each record: select, rename, drop and set fields, with ${…} templates.
Reshape each record: select, rename, drop and set fields, with ${…} templates.
When to use it
Select, rename, remove, and set fields to reshape each input record. Use record templates for calculated text. Check for name collisions and missing inputs before connecting a write destination.
Add and configure
- Add Map fields from the workflow step picker.
- Give the step a recognisable name and connect its required inputs.
- Set the options below. Nested names identify fields within an object or a list item.
- Validate the recipe, inspect the test result, then run it on the intended data.
The step identifier used in the editor’s code view is map.
Settings
| Setting | Accepted value | Required | Default | What it controls |
|---|---|---|---|---|
Drop (drop) | list of string | No | Not specified | Top-level fields to remove. |
Rename (rename) | object of string | No | Not specified | Top-level fields to rename, {old: new}, all at once (two fields can swap). A renamed field replaces any field already named new. |
Select (select) | list of string or null | No | null | Top-level fields to keep, in this order; every other field is left out. Omit to start from the whole record. |
Select Missing (select_missing) | "omit" / "null" | No | "omit" | A selected field the record lacks: omit leaves it out, null writes null. |
Set (set) | object | No | Not specified | Fields to write, {field: value}. Strings may embed ${…} expressions — a JSONPath into the INPUT record, a literal, or a builtin call such as ${lower($.title)}; $${ is a literal ${. |
when (when) | object or null | No | null | Only records matching this predicate are mapped; the rest pass through unchanged. |
Op (when.op) | "eq" / "ne" / "contains" / "exists" / "in" | No | "exists" | Comparison operation (as in filter). |
Path (when.path) | string | Yes | Not specified | JSONPath into each record (e.g. $.status). |
Value (when.value) | value or null | No | null | Comparison value (ignored for 'exists'). |
Inputs and outputs
| Direction | Port | Content | Required | Multiple records |
|---|---|---|---|---|
| Inputs | in | records | Yes | Yes |
| Outputs | out | records | Yes | Yes |
Effects, testing, and recovery
Transforms or passes records without a declared external side effect.
The declared preview behaviour is to execute this step. Reads, processing, or model usage can therefore be real. Read dry runs before using a preview with live connections.
No duplicate-prevention key is declared for this step. The step declares safe replay for its supported recovery path.
Example: Project a fixed set of fields, null when absent
Step settings:
{
"select": [
"id",
"title",
"url"
],
"select_missing": "null"
}
Input records:
[
{
"id": 1,
"raw": {
"html": "…"
},
"title": "A",
"url": "https://a.example"
},
{
"id": 2,
"title": "B"
}
]
Expected output for this example:
[
{
"id": 1,
"title": "A",
"url": "https://a.example"
},
{
"id": 2,
"title": "B",
"url": null
}
]
Example: Rename, drop and derive fields with templates
Step settings:
{
"drop": [
"internal"
],
"rename": {
"desc": "summary"
},
"set": {
"label": "${upper($.code)}: ${$.name}",
"price": "${number($.price)}",
"summary_or_name": "${coalesce($.desc, $.name)}"
}
}
Input records:
[
{
"code": "ab",
"internal": true,
"name": "Widget",
"price": "9.50"
}
]
Expected output for this example:
[
{
"code": "ab",
"label": "AB: Widget",
"name": "Widget",
"price": 9.5,
"summary_or_name": "Widget"
}
]
Example: Flag only the matching records
Step settings:
{
"set": {
"urgent": true
},
"when": {
"op": "eq",
"path": "$.priority",
"value": "high"
}
}
Input records:
[
{
"id": 1,
"priority": "High"
},
{
"id": 2,
"priority": "low"
}
]
Expected output for this example:
[
{
"id": 1,
"priority": "High",
"urgent": true
},
{
"id": 2,
"priority": "low"
}
]
Check the result
Inspect the selected run’s status, counts, errors, and output records. An empty collection can be a valid result, and a completed step can contain per-record failures where the step defines that behaviour. Check the next step’s expected record shape before publishing or delivering the result.