DataMapping NodeTypeCode: data-mapping

When to Use

• Transform API response to 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 column names to DB field names: An imported CSV uses human-readable headers like "First Name", "Date of Birth". Map these to database column names like first_name, dob with appropriate type transforms.
• 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 OrderDTO structure 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 without writing any code — just use dot-notation in SourceField.
• Convert date strings to a standard format: An integration partner sends dates as MM/DD/YYYY. Use the toDate or toDateTime transform to normalize to ISO 8601 before storing in the database.

Configuration

DataMappingRule fields

Supported Transforms

Source Resolution Order

The node resolves the source data in this order (first available wins):

1. InputData["source"] — if the preceding node outputs a field named source, it is used as the source object.
2. Settings.Source — the inline JSON string configured in settings.
3. SourceOutput node lookup — the full output of the named upstream node.

Output Ports

Output Fields

Validation

The node validates on execution (not on save):

• Mappings is required and must be a non-empty array.
• Each rule must have both SourceField and TargetField non-empty strings.
• If a Transform is specified, it must be one of the 16 supported values listed above.
• Type conversion failures (e.g., toInt applied to a non-numeric string) route to the error port with a descriptive message.

Sample Configuration

{
  "nodeType": "data-mapping",
  "settings": {
    "SourceOutput": "crmApiNode",
    "Mappings": [
      { "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.external_id",        "TargetField": "externalId",      "Transform": "toString" }
    ]
  }
}

Sample Output

Success Port

{
  "mappedRecord": {
    "contact_id": "SF-00123456",
    "first_name": "Michael",
    "last_name": "Torres",
    "email_address": "m.torres@company.com",
    "phone_number": "+1-415-555-0182",
    "company_name": "Meridian Logistics",
    "job_title": "Supply Chain Manager",
    "lead_source": "Website",
    "created_date": "2025-03-15"
  },
  "_fieldsProcessed": 9,
  "_nullFieldsSkipped": 2,
  "_transformsApplied": ["concatenate", "format_date", "normalize_phone"]
}

Expression Reference

Node Policies & GuardRails

Pattern Examples

Pattern 1 — Normalize CRM API Response to Internal Order Schema

{
  "SourceOutput": "crmApiNode",
  "Mappings": [
    { "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 — Flatten Nested API Response for Database Insert

An API returns a nested structure. The DataMapping node flattens it to individual columns ready for a DB insert node.

{
  "SourceOutput": "apiResponseNode",
  "Mappings": [
    { "SourceField": "payload.user.id",              "TargetField": "userId" },
    { "SourceField": "payload.user.profile.age",     "TargetField": "age",           "Transform": "toInt" },
    { "SourceField": "payload.user.profile.country", "TargetField": "country",       "Transform": "uppercase" },
    { "SourceField": "payload.subscription.plan",    "TargetField": "plan",          "Transform": "lowercase" },
    { "SourceField": "payload.subscription.expires", "TargetField": "expiryDate",    "Transform": "toDate" },
    { "SourceField": "payload.metadata",             "TargetField": "metaJson",      "Transform": "jsonStringify" }
  ]
}

Pattern 3 — Webhook Payload Validation and Normalization

Immediately after a WebhookTrigger, validate and normalize the inbound payload to ensure all downstream nodes receive clean, typed data.

{
  "SourceOutput": "webhookTriggerNode",
  "Mappings": [
    { "SourceField": "event",        "TargetField": "eventType",   "Transform": "lowercase" },
    { "SourceField": "data.orderId", "TargetField": "orderId",     "Transform": "toString" },
    { "SourceField": "data.amount",  "TargetField": "amountCents", "Transform": "toInt" },
    { "SourceField": "data.currency","TargetField": "currency",    "Transform": "uppercase" },
    { "SourceField": "timestamp",    "TargetField": "eventTime",   "Transform": "toDateTime" }
  ]
}