Writing Mappings

<!-- TIER:1 -->

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.

Quick Reference

Which Mapping System?

Editing existing imports: Many existing imports use Mapper 1.0 even for HTTP and RDBMS adaptor types (pre-dating Mapper 2.0). Always check whether an import uses mappings[] (2.0) or mapping.fields[] (1.0) before modifying -- never mix the two.

Schema Index

Related Skills

• configuring-imports > Quick Reference -- import adaptor types, operation logic, hooks
• configuring-exports > Quick Reference -- export adaptor types, delta syncs, webhooks
• writing-handlebars > Quick Reference -- Handlebars expressions used inside mapping extract fields
• building-flows > How to Build a Flow -- wiring exports and imports into a flow pipeline

<!-- TIER:2 -->

Mapper 2.0 Workflow

The mappings[] array is recursive -- a mapping can contain nested child mappings of the same structure to any depth. This is the core design principle.

1. Check the existing resource

Before modifying mappings, always retrieve the current state of the resource. Check whether it uses Mapper 2.0 (mappings[]) or Mapper 1.0 (mapping.fields[]).

celigo imports get <importId>
celigo account search <keyword>

2. Understand the source data shape

Invoke the upstream export to see real records, or query the source system's metadata for the full field list.

celigo exports invoke <exportId>
celigo metadata fields <sourceConnectionId> <entityType>

3. Understand the target data shape

Query metadata for the target system to discover required fields and types.

celigo metadata types <targetConnectionId>
celigo metadata fields <targetConnectionId> <entityType>

4. Choose the input context

The input context controls what data is available to extract paths. Set via the "Input context" dropdown in the mapper UI:

• `record` (default) -- extract paths reference the record directly. $.user_id accesses the user_id field on the record
• `envelope` -- extract paths reference a wrapper object containing record, job, settings (with connection, flow, integration, flowGrouping), iClient, and import. Record fields shift to $.record.user_id, but you gain access to metadata like $.settings.connection.api_username, $.job.type, $.settings.flow.fieldName

When to use envelope: APIs and tools where you need request context (headers, path params, query params, connection settings) directly in mappings without Handlebars. Also useful on transforms at the beginning of API/tool steps where the envelope exposes the full request context. Envelope context eliminates the need for {{settings.connection.fieldName}} Handlebars expressions -- use $.settings.connection.fieldName instead.

5. Map by data type

Every mapping needs three properties: generate (target field name), dataType (output type), and extract (how to get data from source).

Extract supports three patterns (distinguished by syntax):

• JSON path -- starts with $. (e.g., $.customer.email). Always references the top-level root, even in nested mappings
• Handlebars -- contains {{ (e.g., {{record.firstName}} {{record.lastName}}). For computed values
• Hard-coded -- plain string literal (e.g., "Active", "USD"). Neither $. prefix nor {{

Simple types (string, number, boolean, date) -- direct field-to-field mapping. For dates, set extractDateFormat/generateDateFormat for conversion.

Objects -- set dataType: "object", add child mappings in the mappings[] array. Never use dot notation in generate.

Arrays -- set dataType to an array type (stringarray, numberarray, booleanarray, objectarray, arrayarray) and configure buildArrayHelper[]. Three patterns for object arrays:

• Extract only -- pull existing objects from source (extract: "$.items[*]")