Data Mapping — Configuration

Top-Level Settings

Setting	Type	Required	Default	Description
`inlineDataSource`	string (JSON)	No*	`""`	Inline JSON — a single object or an array of objects. Shared base-class setting (`InlineDataSource` on `BaseNodeExecutorSettings`, config key `inlineDataSource`) — not unique to this node. If non-empty, it wins outright over reading `InputData["items"]`. *Either this or a resolvable upstream `items` input must be present — see Validation on the Overview page.
`dataMappings`	array of MappingRule	Yes*	`[]`	Ordered array of mapping rules, applied to every resolved record. *Required and must be non-empty unless `dataMappingMode` is `"passthrough"`, in which case it may be empty. Rules are applied in the order given; later rules can overwrite earlier ones if they share a `targetField`.
`dataMappingMode`	string	No	`""`	`""` (Default) applies `dataMappings` normally to every record. `"passthrough"` skips all mapping rules and copies each resolved record straight to output.
`sourceDirectivePath` / `sourceDataRootPath` / `sourceDataLeafPath`	string (SmartPath)	No	—	SmartPath fallback, rarely needed. The node already resolves source records from `inlineDataSource` or `InputData["items"]` by default via the shared `ResolveSourceRecords` helper.
`targetDirectivePath` / `targetDataRootPath`	string (SmartPath)	No	—	Optional write-back of the mapped record(s) to another location. Not commonly needed since the output already includes every mapped record under `items[].json`.

MappingRule Schema

Field	Type	Required	Description
`sourceField`	string	Yes	Dot-notation path to the field in the current source record, plus array indexing. Examples: `user.address.city`, `items[0].price`, `data.users[2].email`. No negative indices for field paths (only `substring`'s `start` parameter supports negative offsets — see below).
`targetField`	string	Yes	Flat key name written into the output record. Plain dictionary key assignment — no nested/dot-notation writing on the target side.
`transform`	string	No	One transform string from the catalogue below, applied to the value before writing it to `targetField`. If omitted, the value is copied unchanged.
`transformExpression`	string (JS)	Only when `transform` is `"expression"`	Ignored for every other transform. A JS expression with `item` (the full current record) and `value` (this rule's extracted `sourceField` value) bound as variables — lets one rule read/combine other fields on the same record, not just its own `sourceField`.

No separate parameters object for named transforms

Unlike some other transform systems, there is no transform_params sibling field. Every named transform is a single string; any parameters are colon-suffixed directly onto that same string — e.g. "substring:0:5", "regexreplace:[^0-9]:", "defaultvalue:N/A". Only one transform can be applied per rule (including "expression"); to chain multiple transforms, use two sequential DataMapping nodes.

Built-In Transforms (22)

Transform string	Input → Output	Notes
`"uppercase"`	`"london"` → `"LONDON"`	`str.ToUpperInvariant()`.
`"lowercase"`	`"SMITH"` → `"smith"`	`str.ToLowerInvariant()`.
`"trim"`	`" hi "` → `"hi"`	`str.Trim()`.
`"tostring"`	`42` → `"42"`	Identity string conversion of the value.
`"toint"`	`"42"` → `42`	`int.TryParse`; on failure returns the original value unchanged — not null, not an error.
`"todecimal"`	`"19.99"` → `19.99`	`decimal.TryParse` (invariant culture); same graceful fallback-to-original on failure.
`"toboolean"`	`"true"` → `true`	`bool.TryParse` — only literal `"true"`/`"false"` (case-insensitive), not `"1"`/`"yes"`. Fallback to original on failure.
`"tofloat"`	`"3.14"` → `3.14`	`double.TryParse` (invariant culture); fallback to original on failure.
`"todouble"`	`"3.14"` → `3.14`	Exact alias of `tofloat` — same switch case, identical behavior.
`"todate"`	`"2026-05-23T10:00:00Z"` → `DateTime`	`DateTime.TryParse` with `RoundtripKind`; fallback to original on failure.
`"todatetime"`	`"2026-05-23T10:00:00Z"` → `DateTime`	Exact alias of `todate` — identical behavior.
`"base64encode"`	`"hello"` → `"aGVsbG8="`	UTF-8 → Base64 string.
`"base64decode"`	`"aGVsbG8="` → `"hello"`	Base64 → UTF-8. Returns the original string unchanged if it is not valid Base64.
`"jsonstringify"`	`{ a: 1 }` → `"{\"a\":1}"`	Serializes the original value (not its string form) via `JsonSerializer.Serialize`.
`"jsonparse"`	`"{\"a\":1}"` → `{ a: 1 }`	Parses the string as JSON. Returns the original string unchanged if invalid.
`"nulltoempty"`	`null` → `""`	Special-cased to run even when the value is `null` — `value ?? ""`.
`"emptytonull"`	`""` → `null`	Empty string → `null`; any other value unchanged.
`"defaultvalue:N/A"`	`null` → `"N/A"`	Returns the text after the first colon (the fallback) if the value is `null` or an empty string; otherwise passes the value through unchanged. Also special-cased to run on null input.
`"concat:_suffix"`	`"abc"` → `"abc_suffix"`	Appends the literal text after the colon to the stringified value.
`"substring:0:5"`	`"Hello World"` → `"Hello"`	`start[:length]`. If `length` is omitted, takes to the end of the string.
`"substring:-3"`	`"Hello World"` → `"rld"`	Negative `start` counts from the end (Python-style, e.g. `-3` = last 3 characters).
`"regexreplace:[^0-9]:"`	`"(512) 555-1234"` → `"5125551234"`	`pattern:replacement` (replacement may be empty, as shown). 200ms regex timeout to prevent ReDoS; returns the original string unchanged on timeout or invalid pattern.
`"expression"`	`item.firstName + ' ' + item.lastName` → `"Jane Doe"`	Evaluates `transformExpression` via the same per-record JS expression engine (Jint) CollectionOperation uses for filter/map/reduce. Runs even when `value` is `null` (an expression usually reads from `item`, not necessarily this rule's own `value`). Falls back to the original value on any evaluation error.

Silent fallback on bad numeric/date/expression input

toint, todecimal, toboolean, tofloat/todouble, todate/todatetime, and expression never throw on a parse or evaluation failure — they return the original, untransformed value instead. This means a failed conversion does not route to the error port; the raw (wrong-typed) value simply passes through to targetField. The same applies to an unknown/misspelled transform name: the value passes through unchanged with no error.

Separately, every transform except nulltoempty, defaultvalue:, and expression returns null immediately if the input value is null — none of their conversion logic runs on a null input.

Passthrough Mode & the Data Assigner

When dataMappingMode is "passthrough", dataMappings is not evaluated at all — every resolved record (from inlineDataSource or upstream items) is written directly to the output, unchanged. Validation permits an empty dataMappings array specifically for this mode. The Data Assigner node in the palette (Template ID 10000108, design class data-mapping-passthrough) is this exact node type pre-configured with dataMappingMode: "passthrough" and dataMappings: [].

Designer Forms

This node's configuration is split across independent top-level Atlas Forms:

Form	FormID	Holds
Data Mapping Node	`11010`	`dataMappingMode` (select: Default / Pass Through) and `dataMappings` (`enhanced-json-editor` array editor with a `sourceField`/`targetField`/`transform`/`transformExpression` schema).
Initial Data Source (JSON editor)	`100804`	`inlineDataSource`, rendered via a formatted `enhanced-json-editor` control. This is the active form for this setting.

Note: an older plain-textarea variant of the same inlineDataSource field (Form 100803) previously existed alongside 100804 and rendered as a visible duplicate control in the designer. It has been disabled — do not re-enable it without also removing 100804, or the duplicate will reappear.

Full JSON Configuration Example