Mapper Connector

What this connector is for

Maps JSON data field-by-field into a new shape: each row names a source path to read, an optional transform to apply, and a target path to write to — plus optional per-field validation that can halt the workflow on a bad result. This sits between two other connectors that solve adjacent problems: JSONata is a single freeform expression with no built-in validation; Schema Validator validates a whole document but never reshapes it. Mapper does structured, row-by-row reshaping with reusable transforms, and (via each row's own jsonata-kind transform) still has a JSONata escape hatch when a built-in transform isn't enough.

Source/target paths use dot notation (items.data.request.age) and bracket indices (items[0].tags). A row with kind arrayGroup maps an array item-by-item: its own nested mappings are resolved relative to each source array item, not as flat dot-paths with literal indices — so one arrayGroup row can reshape every element of a source array without listing an index per element.

Map Fields

Maps data into a new object per mappings, then validates the result.

Configuring it

• Input Data — required. The JSON to map (object, array, or JSON string) — can reference a prior step, e.g. {{trigger.body}}.
• Field Mappings — required array of mapping rows. Each row (rendered by a dedicated field-mapping widget, not raw JSON) has:
  • Kind — field (map one value) or arrayGroup (map an array item-by-item via nested mappings).
  • Source Path — where to read from. Leave blank on a field row paired with a defaultValue transform to inject a static/constant value with no real source.
  • Target Path — required. Where to write the result.
  • Transform (field rows only) — optional. Either a built-in transform (toNumber, toString, toBoolean, trim, uppercase, lowercase, dateFormat (needs an outputFormat like YYYY-MM-DD), defaultValue (needs a value, used when the source is missing), split/join (need a delimiter, default ,), round (optional precision), concat (needs sources, an array of extra paths to join with the primary value, and a delimiter), substring (needs start, optional length), replace (needs pattern, optional replacement/flags), toJsonString (optional pretty), or parseJson) — or a JSONata transform: a JSONata expression evaluated with the resolved source value bound to the $value variable and the current source scope (the array item, inside an arrayGroup) bound to $item — e.g. $value & " (" & $item.status & ")".
  • Validation (field rows only) — optional per-field JSON-Schema-flavored checks: required, type, format, pattern, minimum/maximum, minLength/maxLength, enum. Checked against the mapped (target) value, after the full mapping walk completes — not inline per-field — so a required check never false-negatives against a sibling field a later rule hasn't written yet.
  • Skip if Missing — default true: when the source resolves to undefined, the target field is simply omitted rather than written as undefined (a defaultValue transform still runs regardless of this setting).
• Options — optional:
  • On Validation Error — halt (default) or collect. Both modes also catch transform failures (e.g. toNumber on a non-numeric string), not just schema-validation failures.
    • halt: stops the workflow with an HTTP-style error response, like Schema Validator.
    • collect: continues the workflow, exposing every error via the output's validationErrors/hasValidationErrors instead.
  • Error Response (halt mode only) — HTTP Status Code (default 400), Error Response Body ({{errors}} is replaced with the JSON error array), Error Response Headers.

Reading the response

The shape differs by outcome:

• Success, or "collect" mode with errors — a plain result, nested once more under the standard action envelope:
  • {{<stepReference>.response.data.data.<field>}} — the mapped object.
  • {{<stepReference>.response.data.validationErrors}} — present only in collect mode with errors: an array of {ruleId, sourcePath, targetPath, message, keyword}.
  • {{<stepReference>.response.data.hasValidationErrors}} — present only in collect mode with errors.
• Halt mode, validation/transform failure — an HTTP-style result, spread flat (not nested under an inner data):
  • {{<stepReference>.response.status}} / {{<stepReference>.response.data}} — the configured (or default) error status and body.
  • {{<stepReference>.response.validationErrors}} — the same error array, but here a sibling of status/data, not nested under data.

For example, a step named "Map Order" (reference mapOrder) mapping successfully — use {{mapOrder.response.data.data.orderId}}. If it halts on a validation failure instead, that same field is unreachable; check {{mapOrder.response.status}} to branch on it.

Example

Input Data: {"order": {"id": "abc123", "amount": "42.50"}}
Field Mappings:
  - field: order.id -> orderId
  - field: order.amount -> total, transform: toNumber
  - field: order.currency -> currency, transform: defaultValue("USD")

Result: {{mapOrder.response.data.data}} = {"orderId": "abc123", "total": 42.5, "currency": "USD"}.

Preview Mapping

Runs the identical mapping engine as Map Fields, against sample data — but never halts the workflow, regardless of an onValidationError setting (Preview has no Options field at all). Intended for testing a mapping in the designer before wiring it into a real step.

Configuring it

• Sample Data — required. Sample JSON to test the mapping against.
• Field Mappings — required. Identical structure to Map Fields' Field Mappings above.

Reading the response

Always a plain result (never an HTTP-style halt), nested under the action envelope:

• {{<stepReference>.response.data.data.<field>}} — the mapped object.
• {{<stepReference>.response.data.validationErrors}} — present only if errors occurred.
• {{<stepReference>.response.data.hasValidationErrors}} — present only if errors occurred.

Example

Sample Data: {"order": {"id": "abc123", "amount": "not-a-number"}}
Field Mappings: (same as the Map Fields example above)

Result: {{previewMapping.response.data.hasValidationErrors}} = true, with {{previewMapping.response.data.validationErrors}} reporting the toNumber transform failure on order.amount — without ever halting the workflow, so you can inspect it safely while building the mapping.