Configuration Reference
All properties, the mappings array schema, and the full transform catalogue.
Top-Level Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
source | object | string (expression) | No* | — | The source data object to map from. Can be a literal object or a BizFirst expression ({@ $input.current }). *Either source or source_output must be provided. |
source_output | string | No* | — | Name of an upstream node whose output becomes the source. Shorthand for source: "{@ output.NodeName }". Takes precedence over source if both are specified. |
mappings | array of MappingRule | Yes | — | Ordered array of mapping rules. Each rule defines how a source field is read, transformed, and written to the target object. Rules are applied in order; later rules can overwrite earlier ones if they share a target field. |
MappingRule Schema
| Field | Type | Required | Description |
|---|---|---|---|
source_field | string | Yes | Dot-notation path to the field in the source object. Supports array indexing. Examples: user.address.city, items[0].price, meta.tags[2]. |
target_field | string | Yes | Name of the field in the output mapped_data object. Simple names only (no dot notation for nested targets in the current version). |
transform | string | No | Name of the built-in transform to apply. See the transform catalogue below. If omitted, the source value is copied without modification. |
transform_params | object | No | Parameters for transforms that require them (e.g., substring, regexReplace, dateFormat). See per-transform documentation below. |
default_value | any | No | Fallback value used when the source field is null, undefined, or the path does not exist in the source object. The transform is not applied to the default value. |
Built-In Transforms
| Transform | Parameters | Input → Output | Description |
|---|---|---|---|
uppercase | — | "hello" → "HELLO" | Converts the string to upper case. |
lowercase | — | "HELLO" → "hello" | Converts the string to lower case. |
trim | — | " hi " → "hi" | Removes leading and trailing whitespace. |
trimLeft | — | " hi " → "hi " | Removes leading whitespace only. |
trimRight | — | " hi " → " hi" | Removes trailing whitespace only. |
toInt | — | "42" → 42 | Parses the value as a 32-bit integer. Returns null if parsing fails. |
toFloat | — | "3.14" → 3.14 | Parses the value as a floating-point number. Returns null if parsing fails. |
toDate | — | "2026-05-23" → DateTime | Parses the value as a UTC DateTime. Accepts ISO 8601 and common formats. |
toString | — | 42 → "42" | Converts any value to its string representation. |
toBoolean | — | "true" → true | Parses "true"/"false" strings and numeric 1/0 to boolean. |
base64Encode | — | "hello" → "aGVsbG8=" | Base64-encodes a UTF-8 string. |
base64Decode | — | "aGVsbG8=" → "hello" | Decodes a Base64-encoded string to UTF-8. |
substring | start (int), length (int) | "Hello World" → "Hello" | Extracts a substring from start position for length characters. |
regexReplace | pattern (string), replacement (string) | "(512) 555-1234" → "5125551234" | Replaces all matches of the regex pattern with replacement. Supports capture groups. |
defaultValue | fallback (any) | null → "N/A" | Returns fallback if the source value is null or undefined. Equivalent to default_value at the rule level but applied as part of the transform chain. |
dateFormat | format (string, .NET format) | DateTime → "23 May 2026" | Formats a DateTime value using a .NET format string (e.g., dd MMM yyyy, yyyy-MM-dd, MM/dd/yyyy). |
numberFormat | decimals (int), locale (string) | 1234.5 → "1,234.50" | Formats a number with the specified decimal places and locale-aware thousands separator. Locale defaults to en-US. |
Transform Ordering
Only one transform can be applied per mapping rule. If you need to chain multiple transforms (e.g., trim then uppercase), use two sequential Data Mapping nodes, or use a CodeExecute node for complex multi-step transformations.
Full JSON Configuration Example
{
"node_type": "DataMapping",
"name": "NormaliseContact",
"config": {
"source_output": "GetContactFromCRM",
"mappings": [
{
"source_field": "contact.fullName",
"target_field": "displayName",
"transform": "trim"
},
{
"source_field": "contact.emailAddress",
"target_field": "email",
"transform": "lowercase"
},
{
"source_field": "contact.phone",
"target_field": "phoneE164",
"transform": "regexReplace",
"transform_params": { "pattern": "[^0-9]", "replacement": "" }
},
{
"source_field": "contact.createdAt",
"target_field": "memberSince",
"transform": "dateFormat",
"transform_params": { "format": "dd MMM yyyy" }
},
{
"source_field": "contact.accountBalance",
"target_field": "balanceFormatted",
"transform": "numberFormat",
"transform_params": { "decimals": 2, "locale": "en-US" },
"default_value": "0.00"
}
]
}
}