DataMapping NodeTypeCode: data-mapping

The Standard Node Data Envelope

Every node's input and output data — DataMapping included — travels around the workflow inside the same standard envelope. The envelope carries run metadata (timestamp, resource, operation, status, portName, success) plus the actual payload records under items, where each entry wraps its record in a "json" property:

{
  "timestamp": "2026-07-24T01:02:27.8652562Z",
  "triggerTime": "2026-07-24T01:02:27.8652562Z",
  "resource": "trigger",
  "operation": "manual-trigger",
  "status": "success",
  "portName": "main",
  "items": [
    {
      "json": {
        "timestamp": "2026-07-24T01:02:27.8652562Z",
        "triggerTime": "2026-07-24T01:02:27.8652562Z",
        "resource": "trigger",
        "operation": "manual-trigger",
        "status": "success",
        "portName": "main"
      }
    }
  ],
  "success": true
}

DataMapping reads its real records from InputData["items"], unwrapping each entry's "json" value — this is exactly what the shared ResolveSourceRecords/ExtractRecordsFromItems base-class helpers do. It never looks at the outer envelope fields (timestamp/resource/operation/etc.) as data — those are metadata about the upstream run, not part of the record being mapped.

When to Use

• Rename and retype an API response to your internal schema: A third-party CRM API returns fields like contact.full_name and contact.email_address. Map them to your internal schema fields customerName and email with a single DataMapping node, applying trim and lowercase transforms.
• Map CSV/legacy column names to DB field names: An imported CSV uses human-readable headers like "First Name". Map these to database column names like first_name with appropriate type transforms (toint, todate, ...).
• Normalize data from multiple sources into one schema: Orders arrive from Shopify, Magento, and a bespoke ERP — each with different field names. A DataMapping node per source normalizes each to a single internal record shape for consistent downstream processing.
• Extract specific fields from a deeply nested object: An API response contains response.data.attributes.billing.address.city. Map it to a flat billingCity field with dot-notation in sourceField — no code required.
• Combine multiple source fields into one: Build a fullName field from separate firstName/lastName fields with an "expression" transform — no single sourceField can do this alone, since a mapping rule can only read one path per rule.
• Convert loosely-typed strings to real types: An integration partner sends every value as a string. Use toint, todecimal, toboolean, or todate/todatetime to convert before storing. These conversions fail gracefully (see the callout under Supported Transforms) rather than raising an error.
• Map every record in a multi-row upstream result: An upstream query or API call returns an array of many records under items. DataMapping applies the same rules to every record independently and emits one mapped record per input record — you don't need a Loop node just to reshape each row.
• Pass data through untouched: Set dataMappingMode to passthrough (or drop in the pre-built Data Assigner node) when you only need the standard items output envelope around the resolved source record(s), with no field-level mapping at all.

Configuration

MappingRule fields (each entry in dataMappings)

Supported Transforms (22)

Every transform except nulltoempty, defaultvalue:, and expression returns null immediately when the input value is null — they don't run their conversion logic on null.

Multiple Records — One Node Handles the Whole Batch

DataMapping does not process a single object only. When the resolved source (inlineDataSource or upstream items) is an array of many records, DataMapping applies the same dataMappings rules to every record independently and emits one mapped record per input record — each becomes its own entry in the output items array, not one giant array wrapped in a single item. A single object source still produces exactly one output record. The output field recordCount tells you how many records were processed.

Passthrough Mode

Set dataMappingMode to "passthrough" to skip dataMappings entirely and copy each resolved record straight to output — dataMappings may be left empty in this mode. Use passthrough when you need the node purely to move data through the standard output envelope without renaming or converting any field.

The Data Assigner node (Template ID 10000108) is this same node type pre-configured for exactly this: dataMappingMode: "passthrough", dataMappings: []. It appears in the node palette under a separate "Data Assigner" label/icon for discoverability, but at runtime it is the identical data-mapping executor.

Nested Field Access

sourceField supports dot notation and array indexing, evaluated left to right. Examples of increasing depth:

Missing intermediate keys or out-of-bounds indices resolve to null rather than raising an error.

Output Ports

Output Fields

Validation

The node validates on execution:

• Either inlineDataSource must be non-empty, or a usable source path must resolve — otherwise: "sourceDataRootPath is required — specify the variable or key holding the source object".
• dataMappings must be non-empty unless dataMappingMode is "passthrough" — otherwise: "mappings is required and must not be empty".
• Every mapping rule must have both sourceField and targetField non-empty, or validation fails with "Each mapping rule must have a sourceField" / "...targetField".
• At execution time, if the source cannot be resolved at all (no inlineDataSource and no items in the upstream input), the node routes to the error port with "Source data could not be resolved — configure inlineDataSource or a valid sourceDataRootPath".

Sample Configuration

{
  "nodeType": "data-mapping",
  "settings": {
    "dataMappingMode": "",
    "dataMappings": [
      { "sourceField": "contact.full_name",     "targetField": "customerName",  "transform": "trim" },
      { "sourceField": "contact.email_address", "targetField": "email",         "transform": "lowercase" },
      { "sourceField": "contact.address.city",  "targetField": "city",          "transform": "uppercase" },
      { "sourceField": "contact.created_at",    "targetField": "createdDate",   "transform": "todate" },
      { "sourceField": "contact.annual_spend",  "targetField": "annualSpend",   "transform": "todecimal" },
      { "sourceField": "contact.is_active",     "targetField": "isActive",      "transform": "toboolean" },
      { "sourceField": "contact.first_name",    "targetField": "greeting",      "transform": "expression", "transformExpression": "'Hi ' + item.contact.first_name + '!'" }
    ]
  }
}

Sample Output

Success Port

{
  "status": "success",
  "mappingFieldCount": 7,
  "recordCount": 1,
  "items": [
    {
      "json": {
        "customerName": "Michael Torres",
        "email": "[email protected]",
        "city": "SEATTLE",
        "createdDate": "2025-03-15T00:00:00Z",
        "annualSpend": 48250.75,
        "isActive": true,
        "greeting": "Hi Michael!"
      }
    }
  ]
}

Expression Reference

Node Policies & GuardRails

Pattern Examples

See Examples for elaborate, realistic worked examples — basic renaming, combining fields via expression, passthrough/Data Assigner usage, and using inlineDataSource directly.

Pattern 1 — Normalize CRM API Response

{
  "dataMappings": [
    { "sourceField": "data.contact.id",           "targetField": "customerId" },
    { "sourceField": "data.contact.name",         "targetField": "customerName", "transform": "trim" },
    { "sourceField": "data.contact.email",        "targetField": "email",        "transform": "lowercase" },
    { "sourceField": "data.billing.address.city", "targetField": "billingCity",  "transform": "uppercase" },
    { "sourceField": "data.billing.total",        "targetField": "totalAmount",  "transform": "todecimal" },
    { "sourceField": "data.order.created_at",      "targetField": "orderDate",    "transform": "todatetime" }
  ]
}

Pattern 2 — Passthrough via Data Assigner

{
  "dataMappingMode": "passthrough",
  "dataMappings": []
}
// items[].json = each resolved source record, unchanged