writing-mappings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

映射与转换是Celigo集成中的数据重塑层。它们控制着一个系统中的字段如何转换为另一个系统的字段。映射可用于流、API和各种工具中。

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.

有四个系统负责数据重塑：

Mapper 2.0 —— 用于导入的现代递归字段映射（
```
mappings[]
```
数组）。支持嵌套对象、任意深度的数组、查找、条件判断和日期转换。是除NetSuite和Salesforce外所有适配器类型的新导入默认选项
Mapper 1.0 —— 用于NetSuite和Salesforce导入的传统扁平映射（
```
mapping.fields[]
```
/
```
mapping.lists[]
```
）。主体级和子列表字段分别放在独立的扁平数组中。许多在Mapper 2.0出现前创建的旧版HTTP/FTP/RDBMS导入也使用该系统
Transformation 2.0 —— 用于导出的基于规则的数据重塑（
```
transform.expression.rulesTwoDotZero
```
）。内部使用与Mapper 2.0相同的架构。有两种模式："create"（从头构建新记录）或"modify"（编辑现有记录的字段，未映射字段直接传递）
响应映射 —— 简单的提取/生成对，用于将查找或导入响应中的数据带回原记录（流
```
pageProcessors[]
```
中的
```
responseMapping
```
）。使用Transformation 1.0语法

查找功能在所有系统中共享——可以是静态键值映射，也可以是引用LookupCache资源以处理大型/动态数据集。NetSuite导入使用独特的查找系统，会查询NetSuite的实时记录。

方向决定工具选择。映射用于转换发往目标系统的数据——每个导入都需要映射，因为传输中的记录几乎永远无法匹配目标系统的预期格式。转换用于重塑传入的数据——适用于导出、监听器以及API/工具入口阶段。永远不要使用上游转换来匹配目标系统的格式，这是目标导入映射的职责。转换在两种场景下发挥作用：多个源数据汇入一个管道（将每个新源的数据重塑为现有步骤预期的标准记录格式），以及源数据格式混乱（在入口处一次性展平深层嵌套，而非在每个下游映射中处理）。如果只有一个格式规范的数据源，不要为了使用而添加转换——也跳过不重命名任何字段的恒等转换。

Quick Reference

快速参考

Which Mapping System?

选择哪种映射系统？

Context	System	Syntax	Read schema
Import field mapping (HTTP, RDBMS, FTP, S3, etc.)	Mapper 2.0	`mappings[]`	mappings.yml
NetSuite/Salesforce import	Mapper 1.0	`mapping.fields[]`	see import schema (netsuitedistributed.yml, salesforce.yml)
Export data reshaping	Transformation 2.0	`transform{}`	transform.yml
Response mapping (lookup/import carry-back)	Transformation 1.0	extract/generate pairs	response-mapping.yml
Value translation	Lookups	`lookups[]`	lookups.yml

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.

场景	系统	语法	架构文档
导入字段映射（HTTP、RDBMS、FTP、S3等）	Mapper 2.0	`mappings[]`	mappings.yml
NetSuite/Salesforce导入	Mapper 1.0	`mapping.fields[]`	查看导入架构（netsuitedistributed.yml、salesforce.yml）
导出数据重塑	Transformation 2.0	`transform{}`	transform.yml
响应映射（查找/导入数据带回）	Transformation 1.0	提取/生成对	response-mapping.yml
值转换	查找	`lookups[]`	lookups.yml

编辑现有导入： 许多现有导入即使是HTTP和RDBMS适配器类型也使用Mapper 1.0（早于Mapper 2.0）。修改前务必检查导入使用的是

mappings[]

（2.0）还是

mapping.fields[]

（1.0）——切勿混用两者。

Schema Index

架构索引

Schema	Contents
mappings.yml	Mapper 2.0 field definitions (generate, extract, dataType, buildArrayHelper, conditionals)
lookups.yml	Static and dynamic lookup definitions
transform.yml	Transformation 2.0 envelope (mode, expression, script)
response-mapping.yml	Transformation 1.0 extract/generate pairs for response carry-back
netsuitedistributed.yml	NetSuite Mapper 1.0 mapping + lookups
salesforce.yml	Salesforce Mapper 1.0 mapping

架构	内容
mappings.yml	Mapper 2.0字段定义（generate、extract、dataType、buildArrayHelper、条件判断）
lookups.yml	静态和动态查找定义
transform.yml	Transformation 2.0封装（mode、expression、script）
response-mapping.yml	用于响应数据带回的Transformation 1.0提取/生成对
netsuitedistributed.yml	NetSuite Mapper 1.0映射 + 查找
salesforce.yml	Salesforce Mapper 1.0映射

Related Skills

Mapper 2.0 Workflow

Mapper 2.0工作流程

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.

mappings[]

数组是递归的——一个映射可以包含相同结构的嵌套子映射，深度不限。这是核心设计原则。

1. Check the existing resource

1. 检查现有资源

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[]

bash

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

修改映射前，务必获取资源的当前状态。检查它使用的是Mapper 2.0（

mappings[]

）还是Mapper 1.0（

mapping.fields[]

）。

bash

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

2. Understand the source data shape

2. 了解源数据格式

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

bash

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

调用上游导出查看真实记录，或查询源系统的元数据获取完整字段列表。

bash

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

3. Understand the target data shape

3. 了解目标数据格式

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

bash

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

查询目标系统的元数据，发现必填字段和类型。

bash

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

4. Choose the input context

4. 选择输入上下文

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.

输入上下文控制提取路径可访问的数据。通过映射UI中的"Input context"下拉菜单设置：

record
（默认）—— 提取路径直接引用记录。
```
$.user_id
```
访问记录上的
```
user_id
```
字段

envelope
—— 提取路径引用包含

record

、

job

、

settings

（包含

connection

、

flow

、

integration

、

flowGrouping

）、

iClient

和

import

的包装对象。记录字段变为

$.record.user_id

，但你可以访问元数据，如

$.settings.connection.api_username

、

$.job.type

、

$.settings.flow.fieldName

何时使用envelope： 在API和工具中，你需要直接在映射中使用请求上下文（头、路径参数、查询参数、连接设置）而无需Handlebars时。在API/工具步骤开头的转换中也很有用，因为envelope会暴露完整的请求上下文。Envelope上下文无需使用

{{settings.connection.fieldName}}

这样的Handlebars表达式——改用

$.settings.connection.fieldName

即可。

5. Map by data type

5. 按数据类型映射

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[*]"
```
)
Mappings only -- construct objects from individual fields (each
```
buildArrayHelper
```
entry creates one array element)
Extract + mappings -- iterate a source array and reshape each element. Uses the composite object mechanism: array brackets
```
[*]
```
in the extract path collapse to single objects inside the mappings, so
```
$.orders[*].items[*]
```
becomes
```
$.orders.items.fieldName
```
in child extract paths. Parent context remains accessible (e.g.,
```
$.orders.id
```
,
```
$.customerName
```
)

每个映射需要三个属性：

generate

（目标字段名）、

dataType

（输出类型）和

extract

（从源获取数据的方式）。

Extract支持三种模式（通过语法区分）：

JSON路径—— 以
```
$.
```
开头（例如
```
$.customer.email
```
）。始终引用顶级根节点，即使在嵌套映射中也是如此
Handlebars—— 包含
```
{{
```
（例如
```
{{record.firstName}} {{record.lastName}}
```
）。用于计算值
硬编码—— 纯字符串字面量（例如
```
"Active"
```
,
```
"USD"
```
）。既没有
```
$.
```
前缀也没有
```
{{
```

简单类型（字符串、数字、布尔值、日期）—— 直接字段到字段映射。对于日期，设置

extractDateFormat

generateDateFormat

进行转换。

对象—— 设置

dataType: "object"

，在

mappings[]

数组中添加子映射。切勿在

generate

中使用点符号。

数组—— 将

dataType

设置为数组类型（

stringarray

numberarray

booleanarray

objectarray

arrayarray

）并配置

buildArrayHelper[]

。对象数组有三种模式：

仅提取—— 从源获取现有对象（
```
extract: "$.items[*]"
```
）
仅映射—— 从单个字段构造对象（每个
```
buildArrayHelper
```
条目创建一个数组元素）
提取+映射—— 遍历源数组并重塑每个元素。使用复合对象机制：提取路径中的数组括号
```
[*]
```
在映射中会折叠为单个对象，因此
```
$.orders[*].items[*]
```
在子提取路径中变为
```
$.orders.items.fieldName
```
。父上下文仍然可访问（例如
```
$.orders.id
```
,
```
$.customerName
```
）

6. Add lookups for value translation

6. 添加查找以进行值转换

Define lookups alongside mappings and reference them by name via

lookupName

on any mapping.

Static --
```
map
```
object with key-value pairs. Best for small, fixed sets (country codes, status values)
Dynamic --
```
_lookupCacheId
```
referencing a LookupCache resource, with optional
```
extract
```
JSON path to pull a specific field from the cached object
Set
```
allowFailures: true
```
+
```
default
```
to continue processing when lookup keys are missing

在映射旁边定义查找，并通过映射上的

lookupName

按名称引用它们。

静态—— 包含键值对的
```
map
```
对象。最适合小型固定集合（国家代码、状态值）
动态—— 引用LookupCache资源的
```
_lookupCacheId
```
，可选择使用
```
extract
```
JSON路径从缓存对象中提取特定字段
设置
```
allowFailures: true
```
+
```
default
```
，以便在查找键缺失时继续处理

7. Add conditionals where needed

7. 按需添加条件判断

Control when a mapping applies:

record_created

(only on insert),

record_updated

(only on update), or

extract_not_empty

(skip when source is null/empty).

控制映射的应用时机：

record_created

（仅插入时）、

record_updated

（仅更新时）或

extract_not_empty

（源为null/空时跳过）。

Schema reference

架构参考

All Mapper 2.0 field definitions: mappings.yml, lookups.yml

所有Mapper 2.0字段定义：mappings.yml, lookups.yml

Transformation 2.0 Workflow

Transformation 2.0工作流程

Transformation 2.0 reshapes data on exports before it enters the pipeline. It wraps Mapper 2.0 syntax in a transform envelope with a mode selector.

Transformation 2.0在数据进入管道前对导出数据进行重塑。它将Mapper 2.0语法封装在带有模式选择器的转换信封中。

1. Check the existing resource

1. 检查现有资源

Before modifying transforms, retrieve the current export to inspect any existing transform configuration.

bash

celigo exports get <exportId>
celigo account search <keyword>

修改转换前，获取当前导出以检查任何现有转换配置。

bash

celigo exports get <exportId>
celigo account search <keyword>

2. Choose the mode

2. 选择模式

create
-- build a completely new record. Only mapped fields appear in output. Use when the output structure differs significantly from the source
modify
-- edit specific fields on the existing record. Unmapped fields pass through unchanged. Use for surgical adjustments (rename, add, remove a few fields)

create
—— 构建全新记录。输出中仅包含已映射字段。当输出结构与源差异较大时使用
modify
—— 编辑现有记录的特定字段。未映射字段直接传递不变。用于精确调整（重命名、添加、删除少量字段）

3. Write the mappings

3. 编写映射

Same Mapper 2.0 syntax:

generate

dataType

extract

, nested

mappings

buildArrayHelper

, lookups. Everything described in the Mapper 2.0 section above applies here, including input context.

Input context is especially valuable on transforms for APIs and tools -- set it to

envelope

to access the full request context (headers, path params, query params, connection settings) directly via JSON path instead of Handlebars.

使用与Mapper 2.0相同的语法：

generate

dataType

extract

, 嵌套

mappings

buildArrayHelper

, 查找。上述Mapper 2.0部分描述的所有内容均适用于此，包括输入上下文。

输入上下文在API和工具的转换中尤其有用——将其设置为

envelope

，即可通过JSON路径直接访问完整的请求上下文（头、路径参数、查询参数、连接设置），而非使用Handlebars。

4. Configure the transform envelope

4. 配置转换信封

Set

transform.type: "expression"

expression.version: "2"

, then place

mappings[]

and

lookups[]

under

expression.rulesTwoDotZero

with the chosen

mode

Script alternative: Set

transform.type: "script"

with

script._scriptId

and

script.function

for programmatic transforms when expression rules aren't sufficient.

设置

transform.type: "expression"

expression.version: "2"

，然后将

mappings[]

和

lookups[]

放在

expression.rulesTwoDotZero

下，并选择相应的

mode

。

脚本替代方案： 设置

transform.type: "script"

并使用

script._scriptId

和

script.function

，在表达式规则不足时进行程序化转换。

Schema reference

架构参考

All Transformation 2.0 field definitions: transform.yml, mappings.yml, lookups.yml

所有Transformation 2.0字段定义：transform.yml, mappings.yml, lookups.yml

Mapper 1.0 Reference (NetSuite and Salesforce)

Mapper 1.0参考（NetSuite和Salesforce）

NetSuite and Salesforce imports use the older flat mapping structure. Two arrays within the

mapping

object:

mapping.fields[]
-- body-level field mappings. Each entry has
```
extract
```
(source path) or
```
hardCodedValue
```
(static value),
```
generate
```
(target field ID), and optional
```
lookupName
```
,
```
dataType
```
,
```
internalId
```
,
```
immutable
```
,
```
discardIfEmpty
```
,
```
conditional
```
mapping.lists[]
-- sublist/line-item mappings. Each entry has
```
generate
```
(sublist ID, e.g.,
```
"item"
```
),
```
jsonPath
```
(source array path), and
```
fields[]
```
(column mappings with the same properties as body fields, plus
```
isKey
```
for matching existing lines)

NetSuite lookups are different -- they query live NetSuite records using

recordType

searchField

resultField

, and

operator

. Not static maps. Defined in

netsuite_da.lookups[]

, referenced by

lookupName

in field mappings. To discover valid field IDs for

searchField

and

resultField

, run

celigo metadata fields <connectionId> <recordType>

— the returned field IDs are the exact values to use.

Salesforce lookups follow the same Mapper 1.0 pattern but the lookup structure is simpler.

Sublist field discovery: For NetSuite

mapping.lists[].generate

, the sublist name (e.g.,

"item"

"addressbook"

) comes from

celigo metadata fields <connectionId> <recordType>

— sublists appear as field groups. For Salesforce related lists, use

celigo metadata fields <connectionId> <sObjectType>

to discover relationship fields and child object names for

distributed.relatedLists[].sObjectType

NetSuite和Salesforce导入使用较旧的扁平映射结构。

mapping

对象内有两个数组：

mapping.fields[]
—— 主体级字段映射。每个条目包含
```
extract
```
（源路径）或
```
hardCodedValue
```
（静态值）、
```
generate
```
（目标字段ID），以及可选的
```
lookupName
```
,
```
dataType
```
,
```
internalId
```
,
```
immutable
```
,
```
discardIfEmpty
```
,
```
conditional
```
mapping.lists[]
—— 子列表/行项目映射。每个条目包含
```
generate
```
（子列表ID，例如
```
"item"
```
）、
```
jsonPath
```
（源数组路径）和
```
fields[]
```
（列映射，与主体字段属性相同，外加
```
isKey
```
用于匹配现有行）

NetSuite查找有所不同——它们使用

recordType

searchField

resultField

和

operator

查询NetSuite的实时记录。不是静态映射。在

netsuite_da.lookups[]

中定义，通过字段映射中的

lookupName

引用。要查找

searchField

和

resultField

的有效字段ID，运行

celigo metadata fields <connectionId> <recordType>

—— 返回的字段ID就是要使用的确切值。

Salesforce查找遵循相同的Mapper 1.0模式，但查找结构更简单。

子列表字段发现： 对于NetSuite的

mapping.lists[].generate

，子列表名称（例如

"item"

"addressbook"

）来自

celigo metadata fields <connectionId> <recordType>

—— 子列表显示为字段组。对于Salesforce相关列表，使用

celigo metadata fields <connectionId> <sObjectType>

发现关系字段和子对象名称，用于

distributed.relatedLists[].sObjectType

。

Schema reference

架构参考

NetSuite Mapper 1.0: see

mapping

and

lookups

in the configuring-imports skill's netsuitedistributed.yml Salesforce Mapper 1.0: see

mapping

in the configuring-imports skill's salesforce.yml

NetSuite Mapper 1.0：查看配置导入技能中的

mapping

和

lookups

，见netsuitedistributed.yml Salesforce Mapper 1.0：查看配置导入技能中的

mapping

，见salesforce.yml

Response Mapping Reference (Transformation 1.0)

响应映射参考（Transformation 1.0）

Response mapping extracts fields from a lookup or import API response back into the original record. It lives on the flow's

pageProcessors[]

entry, not on the resource itself -- but it's planned when building the resource.

Two sections:

fields.type[]
-- field-level extract/generate pairs using dot notation
lists.type[]
-- array mappings with
```
generate
```
(target array name) and
```
fields[]
```
(column mappings)

For lookup exports: the response contains

data[]

and

errors[]

. Use

data[0].fieldName

for single results,

data[*].fieldName

when multiple results are expected.

For imports: the response is available via

_json

. Use

_json.fieldName

(e.g.,

_json.id

for a created record's ID,

_json.output.1.content.0.text

for AI model responses).

响应映射从查找或导入API响应中提取字段并带回原记录。它位于流的

pageProcessors[]

条目中，而非资源本身——但在构建资源时就需要规划。

分为两部分：

fields.type[]
—— 使用点符号的字段级提取/生成对
lists.type[]
—— 数组映射，包含
```
generate
```
（目标数组名称）和
```
fields[]
```
（列映射）

对于查找导出： 响应包含

data[]

和

errors[]

。单个结果使用

data[0].fieldName

，预期多个结果时使用

data[*].fieldName

。

对于导入： 响应可通过

_json

访问。使用

_json.fieldName

（例如

_json.id

获取创建记录的ID，

_json.output.1.content.0.text

获取AI模型响应）。

Schema reference

架构参考

All response mapping field definitions: response-mapping.yml

所有响应映射字段定义：response-mapping.yml

CLI Commands

CLI命令

bash

undefined

bash

undefined

Discover resources

发现资源

celigo account search <keyword> # Find imports/exports by name celigo imports get <importId> # Inspect existing import (check mappings vs mapping) celigo exports get <exportId> # Inspect existing export (check transform)

celigo account search <keyword> # 按名称查找导入/导出 celigo imports get <importId> # 检查现有导入（确认使用mappings还是mapping） celigo exports get <exportId> # 检查现有导出（确认transform）

Understand data shapes

了解数据格式

celigo exports invoke <exportId> # See real source records celigo metadata types <connectionId> # List entity types celigo metadata fields <connectionId> <type> # List fields for an entity

celigo exports invoke <exportId> # 查看真实源记录 celigo metadata types <connectionId> # 列出实体类型 celigo metadata fields <connectionId> <type> # 列出实体的字段

Update mappings (GET -> modify -> PUT)

更新映射（GET -> 修改 -> PUT）

celigo imports set <importId> <key>=<value> [<key2>=<value2> ...] # Field-level edit (dot/bracket paths, JSON values) celigo exports set <exportId> <key>=<value> [<key2>=<value2> ...] celigo imports update <importId> < import.json # Full PUT replace from stdin JSON celigo exports update <exportId> < export.json


<!-- TIER:3 -->

celigo imports set <importId> <key>=<value> [<key2>=<value2> ...] # 字段级编辑（点/括号路径，JSON值） celigo exports set <exportId> <key>=<value> [<key2>=<value2> ...] celigo imports update <importId> < import.json # 从标准输入JSON进行完整PUT替换 celigo exports update <exportId> < export.json


<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Before submitting any mapping configuration, verify:

Correct system identified --
```
mappings[]
```
for Mapper 2.0,
```
mapping.fields[]
```
for Mapper 1.0; never mix
status: "Active"
on every mapping entry -- API rejects entries without it
No dot notation in
generate
-- use nested
```
dataType: "object"
```
with child
```
mappings[]
```
instead
Extract paths start from root --
```
$.
```
paths always reference the top-level input, even in nested mappings
Array mappings have
buildArrayHelper
-- required for all
```
*array
```
dataTypes
Lookups defined and referenced -- every
```
lookupName
```
on a mapping has a corresponding entry in
```
lookups[]
```

Date formats specified --

extractDateFormat

generateDateFormat

set when

dataType: "date"

Full resource PUT -- GET the complete resource first, modify only the mapping section, PUT the whole object back
Response mapping on the flow --
```
responseMapping
```
lives on
```
flow.pageProcessors[]
```
, not on the import resource itself
Composite object paths adjusted -- when
```
buildArrayHelper
```
has both
```
extract
```
and
```
mappings
```
, child extract paths drop the
```
[*]
```
brackets

提交任何映射配置前，请验证：

已识别正确的系统——Mapper 2.0使用
```
mappings[]
```
，Mapper 1.0使用
```
mapping.fields[]
```
；切勿混用
每个映射条目都设置了
status: "Active"
——API会拒绝缺少该字段的条目
generate
中未使用点符号——改用嵌套的
```
dataType: "object"
```
和子
```
mappings[]
```
提取路径从根节点开始——
```
$.
```
路径始终引用顶级输入，即使在嵌套映射中也是如此
数组映射包含
buildArrayHelper
——所有
```
*array
```
类型的dataType都需要该配置
查找已定义并被引用——映射上的每个
```
lookupName
```
在
```
lookups[]
```
中都有对应的条目

已指定日期格式——当

dataType: "date"

时设置

extractDateFormat

generateDateFormat

完整资源PUT——先获取完整资源，仅修改映射部分，再PUT整个对象
流上已配置响应映射——
```
responseMapping
```
位于
```
flow.pageProcessors[]
```
，而非导入资源本身
复合对象路径已调整——当
```
buildArrayHelper
```
同时包含
```
extract
```
和
```
mappings
```
时，子提取路径需去掉
```
[*]
```
括号

Gotchas

注意事项

Existing imports may use Mapper 1.0 even for HTTP/RDBMS/FTP. Mapper 2.0 is the default for new imports, but many older imports across all adaptor types use Mapper 1.0. Always check the existing format before editing --
```
mappings[]
```
means 2.0,
```
mapping.fields[]
```
means 1.0. Never mix.
Extract paths always reference the root of the input context. Even in deeply nested Mapper 2.0 mappings,
```
$.
```
paths start from the top level (the record in
```
record
```
context, or the envelope in
```
envelope
```
context), not the current nesting level.
Composite object collapses arrays to single objects. When
```
buildArrayHelper
```
has both
```
extract
```
and
```
mappings
```
, array brackets in the extract path are replaced with single objects in child mapping contexts.
```
$.orders[*].items[*]
```
becomes
```
$.orders.items.fieldName
```
inside the mappings.
Response mapping uses Transformation 1.0 syntax, not 2.0. Don't use
```
rulesTwoDotZero
```
structure in
```
responseMapping
```
. It uses simple extract/generate pairs with dot notation.
NetSuite lookups query live data. A NetSuite import's
```
netsuite_da.lookups[]
```
searches NetSuite records at runtime (
```
recordType
```
,
```
searchField
```
,
```
resultField
```
), unlike Mapper 2.0 static
```
map
```
lookups.
generate
must not use dot notation in Mapper 2.0. Build nested structures with
```
dataType: "object"
```
and child
```
mappings[]
```
.
```
"generate": "customer.name"
```
silently creates a field literally named
```
"customer.name"
```
.
Empty
generate
indicates inner array in
arrayarray
. For nested array structures, inner array mappings have no
```
generate
```
field -- this is expected, not an error.
Transformation 2.0 "modify" passes through unmapped fields. "Create" mode only outputs explicitly mapped fields. Choose based on whether you want a clean slate or surgical edits.
PUT erases omitted fields on the parent resource. When updating mappings on an import or transform on an export, always GET the full resource first, modify the mapping/transform section, then PUT the complete object. The
```
set
```
command handles this.

现有导入即使是HTTP/RDBMS/FTP也可能使用Mapper 1.0。Mapper 2.0是新导入的默认选项，但许多旧版导入（涵盖所有适配器类型）仍使用Mapper 1.0。修改前务必检查现有格式——
```
mappings[]
```
表示2.0，
```
mapping.fields[]
```
表示1.0。切勿混用。
提取路径始终引用输入上下文的根节点。即使在深度嵌套的Mapper 2.0映射中，
```
$.
```
路径也从顶级开始（
```
record
```
上下文的记录，或
```
envelope
```
上下文的信封），而非当前嵌套级别。
复合对象会将数组折叠为单个对象。当
```
buildArrayHelper
```
同时包含
```
extract
```
和
```
mappings
```
时，提取路径中的数组括号在子映射上下文中会替换为单个对象。
```
$.orders[*].items[*]
```
在映射内部变为
```
$.orders.items.fieldName
```
。
响应映射使用Transformation 1.0语法，而非2.0。不要在
```
responseMapping
```
中使用
```
rulesTwoDotZero
```
结构。它使用简单的点符号提取/生成对。
NetSuite查找查询实时数据。NetSuite导入的
```
netsuite_da.lookups[]
```
在运行时搜索NetSuite记录（
```
recordType
```
,
```
searchField
```
,
```
resultField
```
），与Mapper 2.0的静态
```
map
```
查找不同。
Mapper 2.0中
generate
不能使用点符号。使用
```
dataType: "object"
```
和子
```
mappings[]
```
构建嵌套结构。
```
"generate": "customer.name"
```
会静默创建一个字面名为
```
"customer.name"
```
的字段。
arrayarray
中内部数组的
generate
为空。对于嵌套数组结构，内部数组映射没有
```
generate
```
字段——这是预期行为，而非错误。
Transformation 2.0的"modify"模式会传递未映射字段。"Create"模式仅输出显式映射的字段。根据需要选择是从头构建还是精确编辑。
PUT会覆盖父资源中省略的字段。更新导入的映射或导出的转换时，务必先获取完整资源，修改映射/转换部分，再PUT完整对象。
```
set
```
命令会处理此操作。

Common Errors

常见错误

Error	Cause	Fix
"Mapping object must have status field present"	Missing `status` on a mapping entry	Add `status: "Active"` to every mapping object
Import silently creates field named `"customer.name"`	Dot notation in `generate`	Use nested `dataType: "object"` with child `mappings[]`
Mapped fields missing in output	Using Mapper 2.0 syntax on a Mapper 1.0 import (or vice versa)	Check existing format: `mappings[]` = 2.0, `mapping.fields[]` = 1.0
Extract returns `null` in nested mapping	Extract path relative to nesting level	Extract paths always start from root ( `$.` ), not the current level
Array output is empty	Missing `buildArrayHelper` on array dataType	Add `buildArrayHelper[]` for all `*array` dataTypes
Lookup key not found / processing stops	`allowFailures` not set on lookup	Set `allowFailures: true` and provide a `default` value
Response mapping not applied	`responseMapping` placed on the import resource	Move to `flow.pageProcessors[]` entry for that import
Composite object paths return wrong data	`[*]` brackets still in child extract paths	Drop `[*]` -- arrays collapse to single objects inside `buildArrayHelper` mappings
Date values malformed in output	Missing date format configuration	Set `extractDateFormat` and `generateDateFormat` on date mappings
PUT overwrites entire resource	Partial JSON sent without GET first	Always GET full resource, modify mapping section, PUT complete object

错误	原因	修复方案
"Mapping object must have status field present"	映射条目缺少 `status`	为每个映射对象添加 `status: "Active"`
导入静默创建名为 `"customer.name"` 的字段	`generate` 中使用了点符号	使用嵌套的 `dataType: "object"` 和子 `mappings[]`
输出中缺少已映射字段	在Mapper 1.0导入中使用了Mapper 2.0语法（反之亦然）	检查现有格式： `mappings[]` = 2.0， `mapping.fields[]` = 1.0
嵌套映射中Extract返回 `null`	提取路径相对于嵌套级别	提取路径始终从根节点开始（ `$.` ），而非当前级别
数组输出为空	数组类型的dataType缺少 `buildArrayHelper`	为所有 `*array` 类型的dataType添加 `buildArrayHelper[]`
查找键未找到 / 处理停止	查找未设置 `allowFailures`	设置 `allowFailures: true` 并提供 `default` 值
响应映射未生效	`responseMapping` 放在了导入资源上	移至该导入对应的 `flow.pageProcessors[]` 条目
复合对象路径返回错误数据	子提取路径中仍包含 `[*]` 括号	去掉 `[*]` ——在 `buildArrayHelper` 映射中数组会折叠为单个对象
输出中日期格式错误	缺少日期格式配置	在日期映射上设置 `extractDateFormat` 和 `generateDateFormat`
PUT覆盖了整个资源	未先GET就发送了部分JSON	务必先获取完整资源，修改映射部分，再PUT完整对象

writing-mappings

Original

Translation

Writing Mappings and Transforms

编写映射与转换

Mapping Systems

映射系统

Quick Reference

快速参考

Which Mapping System?

选择哪种映射系统？

Schema Index

架构索引

Related Skills

相关技能

Mapper 2.0 Workflow

Mapper 2.0工作流程

1. Check the existing resource

1. 检查现有资源

2. Understand the source data shape

2. 了解源数据格式

3. Understand the target data shape

3. 了解目标数据格式

4. Choose the input context

4. 选择输入上下文

5. Map by data type

5. 按数据类型映射

6. Add lookups for value translation

6. 添加查找以进行值转换

7. Add conditionals where needed

7. 按需添加条件判断

Schema reference

架构参考

Transformation 2.0 Workflow

Transformation 2.0工作流程

1. Check the existing resource

1. 检查现有资源

2. Choose the mode

2. 选择模式

3. Write the mappings

3. 编写映射

4. Configure the transform envelope

4. 配置转换信封

Schema reference

架构参考

Mapper 1.0 Reference (NetSuite and Salesforce)

Mapper 1.0参考（NetSuite和Salesforce）

Schema reference

架构参考

Response Mapping Reference (Transformation 1.0)

响应映射参考（Transformation 1.0）

Schema reference

架构参考

CLI Commands

CLI命令

Discover resources

发现资源

Understand data shapes

了解数据格式

Update mappings (GET -> modify -> PUT)

更新映射（GET -> 修改 -> PUT）

Pre-Submit Checklist

提交前检查清单

Gotchas

注意事项

Common Errors

常见错误