Writing Mappings and Transforms

Mappings and transforms are the data reshaping layer in Celigo integrations. They control how fields from one system translate into fields for another. Mappings are used across flows, APIs, and tools.

Mapping Systems

Four systems handle data reshaping:

• Mapper 2.0 -- modern recursive field mapping on imports (mappings[] array). Handles nested objects, arrays of any depth, lookups, conditionals, and date conversions. Default for new imports on all adaptor types except NetSuite and Salesforce
• Mapper 1.0 -- legacy flat mapping on NetSuite and Salesforce imports (mapping.fields[] / mapping.lists[]). Body-level and sublist fields in separate flat arrays. Also present on many older HTTP/FTP/RDBMS imports created before Mapper 2.0 existed
• Transformation 2.0 -- rule-based data reshaping on exports (transform.expression.rulesTwoDotZero). Uses the same Mapper 2.0 schema internally. Two modes: "create" (build new record from scratch) or "modify" (edit fields on existing record, unmapped fields pass through)
• Response mapping -- simple extract/generate pairs that carry data from a lookup or import response back into the record (responseMapping on flow pageProcessors[]). Uses Transformation 1.0 syntax

Lookups are shared across all systems -- static key-value maps or references to LookupCache resources for large/dynamic datasets. NetSuite imports use a distinct lookup system that queries live NetSuite records.

Direction decides the tool. Mappings translate data going out to a destination -- every import needs them, because the in-flight record almost never matches what the destination expects. Transformations reshape data coming in -- on exports, listeners, and API/tool entry stages. Never use an upstream transformation to match a destination's shape; that's the destination import's mapping. Transformations earn their keep in two situations: multiple sources feeding one pipeline (reshape each new source to the canonical record shape the existing steps expect) and genuinely messy source data (flatten deep nesting once at entry instead of fighting it in every downstream mapping). With a single well-shaped source, don't add a transform just because you can -- and skip identity transforms that rename nothing.